diff --git a/README.md b/README.md
index 87cf17920..3de5331c1 100644
--- a/README.md
+++ b/README.md
@@ -576,7 +576,13 @@ Every MCP tool can be invoked as a local, one-shot command. CLI tools neither st
 
 Commands that mutate graph data use shared OS-backed, per-project locks. This serializes conflicting work from CLI and MCP sessions on the same project while allowing unrelated projects to proceed independently.
 
-When stderr is an interactive terminal, the CLI automatically shows lifecycle and indexing progress. Pass `--progress` to force the same feedback when stderr is redirected or the command is run non-interactively. Progress is written only to stderr; stdout remains reserved for the command result, so pipes and scripts stay machine-safe. Pass `--json` when the full MCP result envelope is needed.
+When stderr is an interactive terminal, the CLI automatically shows lifecycle and indexing progress. Pass `--progress` to force the same feedback when stderr is redirected or the command is run non-interactively. Pass `--quiet` to disable automatic terminal progress and ordinary diagnostics while retaining errors; it cannot be combined with `--progress` or outer `cli --verbose`. Routine informational logs are quiet by default; pass outer `cli --verbose` to include them. Progress and logs use stderr while stdout remains reserved for the command result. Read tools return a compact tree by default; pass a tool's `--format json` for machine-readable payload JSON, or outer `--json` for the full MCP envelope.
+
+Large compact-tree tables may start with a response-local `<section>_refs` directory and an explicit `<section>_ref_rule`. A cell such as `@0+handler.go` reconstructs to ref `0`'s prefix plus `handler.go`. References are local to that sibling `<section>` table and expansion is non-recursive: entries inside `<section>_refs` are always literal prefixes. This is limited to declared path and qualified-name columns and activates only when the exact rendered table is at least 15% and 64 bytes smaller and a conservative model-neutral token-shape proxy also improves by at least 1%. Search and trace likewise render direct and prefix-grouped tree shapes and keep the smaller complete representation, so singleton or scattered answers do not pay directory overhead. Keys are declared once per table but never cryptically abbreviated, and `--format json` keeps stable literal strings for machine consumers. Both gates are deterministic; exact token counts still depend on the caller's tokenizer.
+
+Lean responses truncate semantically, never by cutting arbitrary bytes from code or identifiers. Ranked graph rows are retained ahead of raw grep rows and diagnostic summaries; omitted rows/sections report totals, `has_more`, and a strictly advancing continuation offset or cursor. If even the first whole row cannot fit, CBM asks for a higher budget and emits no self-looping cursor. `max_output_tokens` is model-neutral sizing guidance: CBM enforces a deterministic ceiling of four UTF-8 bytes per requested token, so it is not a tokenizer-exact count. Detail flags such as `diagnostics`, `source_mode`, and `detail` opt into heavier fields. `search_code` pages ranked rows with `result_limit`/`result_offset` (`limit` remains a compatibility alias), raw rows with `raw_limit`/`raw_offset`, and directory summaries with `directory_limit`/`directory_offset`. Raw lines default to a UTF-8-safe match-centered preview; each row reports `content_start_byte`, returned/total byte counts, match byte bounds when known, and a content continuation offset. Pass `raw_content_offset` to page the original line without moving the raw-row cursor. `match_limit` and `source_max_lines` bound per-result details, with exact omission metadata. `detect_changes` pages changed files, impacted symbols, and module summaries independently; prefer its snapshot-bound `*_cursor` continuations, which reject changed commits, worktree bytes, graph generation, or semantic arguments instead of silently skipping or duplicating rows.
+
+Every response is standard UTF-8. Identifiers, paths, and raw search previews preserve POSIX byte-string identities: a preserved value containing malformed UTF-8 is emitted reversibly as `@bytes:<lowercase hex of every original byte>`. A valid preserved value that literally begins with the reserved `@bytes:` or `@utf8:` prefix is emitted as `@utf8:<original value>`, so decoding is unambiguous: strip one `@utf8:` prefix for literal UTF-8, or hex-decode one `@bytes:` prefix for original bytes. Ordinary valid UTF-8 is unchanged and pays no output-token overhead. To keep code readable, source bodies replace malformed UTF-8 with U+FFFD; use the pageable raw search preview when byte-exact source inspection is required.
 
 Use `cli <tool> --help` to see the flags generated from that tool's input schema:
 
@@ -591,7 +597,10 @@ codebase-memory-mcp cli query_graph --project my-project --query 'MATCH (f:Funct
 
 # Force human-readable progress without contaminating stdout.
 codebase-memory-mcp cli --progress index_repository --repo-path /path/to/repo
-codebase-memory-mcp cli search_graph --project my-project --label Function | jq '.results[].name'
+# Suppress automatic terminal progress and non-error diagnostics.
+codebase-memory-mcp cli --quiet list_projects --format json
+codebase-memory-mcp cli search_graph --project my-project --label Function --format json
+codebase-memory-mcp cli list_projects --format json --detail stats | jq '.projects[].name'
 ```
 
 JSON arguments can also be piped on stdin. Inline JSON remains accepted for backward compatibility but is deprecated in favor of flags, `--args-file`, or stdin.
@@ -611,7 +620,7 @@ JSON arguments can also be piped on stdin. Inline JSON remains accepted for back
 
 | Tool | Description |
 |------|-------------|
-| `search_graph` | Structured search by label, name pattern, file pattern, degree filters. Pagination via limit/offset. |
+| `search_graph` | Structural, BM25, and semantic search. Page structural rows with `offset`/`limit` and ranked semantic rows independently with `semantic_offset`/`semantic_limit`. |
 | `trace_path` | BFS traversal — who calls a function and what it calls (alias: `trace_call_path`). Depth 1-5. |
 | `detect_changes` | Map git diff to affected symbols + blast radius with risk classification. |
 | `query_graph` | Execute Cypher-like graph queries (read-only). |
@@ -674,7 +683,7 @@ codebase-memory-mcp config reset auto_index              # reset to default
 | `CBM_CACHE_DIR` | `~/.cache/codebase-memory-mcp` | Override the database storage directory. All project indexes and config are stored here. One account can use only one canonical cache root at a time; close active CBM sessions/commands before switching it. |
 | `CBM_DIAGNOSTICS` | `false` | Set to `1` or `true` to enable the shared daemon's periodic `snapshot.json` and retained `trajectory.ndjson` below a fresh owner-private directory in the system temp directory. Exact paths are logged by `diagnostics.start`. |
 | `CBM_DOWNLOAD_URL` | *(GitHub releases)* | Override the download URL for updates. Used for testing or self-hosted deployments. |
-| `CBM_LOG_LEVEL` | `info` | Set the minimum log level. Accepted values (case-insensitive): `debug`, `info`, `warn`, `error`, `none` — or their numeric equivalents `0`–`4` matching the internal enum. Thin-frontend messages go to that session's stderr; detached daemon events go to `${CBM_CACHE_DIR}/logs/cbm-daemon.log`. Stdout is reserved for MCP JSON-RPC. |
+| `CBM_LOG_LEVEL` | role-aware | Set the minimum log level. Thin MCP/CLI/hook frontends default to `warn`; the detached daemon and its supervised index workers default to `info` so lifecycle and liveness records remain available. Accepted values (case-insensitive): `debug`, `info`, `warn`, `error`, `none` — or their numeric equivalents `0`–`4`. A physical worker retains INFO liveness records even under a stricter override because its private log drives the supervisor's no-progress timeout. Frontend messages go to that session's stderr; detached daemon events go to `${CBM_CACHE_DIR}/logs/cbm-daemon.log`. Stdout is reserved for MCP JSON-RPC. |
 | `CBM_WORKERS` | *(detected)* | Override the parallel-indexing worker count returned by `cbm_default_worker_count`. Useful inside containers where `sysconf(_SC_NPROCESSORS_ONLN)` reports host CPUs rather than the cgroup's effective quota. Range 1–256; invalid values are ignored with a warning. |
 | `CBM_MEM_BUDGET_MB` | *(detected)* | Override the in-memory graph budget with an explicit cap in MiB, taking precedence over the `ram_fraction × total_RAM` default. Useful on bare-metal hosts without a cgroup limit, or to pin a budget *below* the cgroup limit so headroom is left for sibling processes. Must be a positive integer; it is clamped to detected total RAM (logged as `mem.budget.clamped`), and non-numeric or non-positive values are ignored with a warning (`mem.budget.env.invalid`). |
 | `CBM_DUMP_VERIFY_MIN_RATIO` | `0.5` | After indexing, compare persisted SQLite node count to the in-memory dump count. When persisted nodes fall below this fraction of committed nodes (and committed > 50), `index_repository` returns `status:"degraded"` instead of silent `indexed`. Range 0–1; set `0` to disable. Invalid values are ignored with a warning. |
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index fae2af19e..46bfa5824 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -120,7 +120,7 @@ These environment variables affect runtime behavior:
 | `CBM_CACHE_DIR` | `~/.cache/codebase-memory-mcp` | Override the cache directory used for indexes, `_config.db`, and UI `config.json`. |
 | `CBM_DIAGNOSTICS` | `false` | Enable periodic `snapshot.json` and retained `trajectory.ndjson` below a fresh owner-private directory in the system temp directory. The daemon records the randomized paths in the `diagnostics.start` discovery record (a single JSON line) in `${CBM_CACHE_DIR}/logs/cbm-daemon.log`; that one record is emitted even when `CBM_LOG_LEVEL` suppresses ordinary logging, so the paths always remain discoverable. |
 | `CBM_DOWNLOAD_URL` | GitHub releases | Override the update download URL. |
-| `CBM_LOG_LEVEL` | `info` | Set the log level to `debug`, `info`, `warn`, `error`, or `none` (or `0`-`4`). Thin-frontend messages use that session's stderr; detached daemon events use `${CBM_CACHE_DIR}/logs/cbm-daemon.log`. |
+| `CBM_LOG_LEVEL` | role-aware | Set the log level to `debug`, `info`, `warn`, `error`, or `none` (or `0`-`4`). Thin MCP/CLI/hook frontends default to `warn`; the detached daemon and supervised index workers default to `info`. Physical workers retain INFO liveness records because their private logs drive the supervisor's no-progress timeout. Frontend messages use that session's stderr; detached daemon events use `${CBM_CACHE_DIR}/logs/cbm-daemon.log`. |
 | `CBM_WORKERS` | auto-detected | Override the indexing worker count. |
 
 Environment used by daemon-owned components—such as diagnostics, daemon logging, and process-wide indexing resource limits—is captured from the first daemon-backed session that starts the daemon. Later sessions join the existing process and cannot replace those values. To change them, close every daemon-backed session, update the relevant agent configurations consistently, and restart a session. `CBM_ALLOWED_ROOT` remains session-specific, a conflicting `CBM_CACHE_DIR` is rejected, and one-shot CLI commands use their own current environment without starting the daemon.
diff --git a/graph-ui/src/components/NodeDetailPanel.test.tsx b/graph-ui/src/components/NodeDetailPanel.test.tsx
index 5a9455d09..12c72b1a4 100644
--- a/graph-ui/src/components/NodeDetailPanel.test.tsx
+++ b/graph-ui/src/components/NodeDetailPanel.test.tsx
@@ -68,6 +68,12 @@ describe("NodeDetailPanel code preview + deep-link", () => {
     /* …but was NOT parsed into a real <script> element, and did not execute. */
     expect(container.querySelector("script")).toBeNull();
     expect((window as unknown as { __pwned?: boolean }).__pwned).toBeUndefined();
+    expect(callToolMock).toHaveBeenCalledWith("get_code_snippet", {
+      qualified_name: "app::render",
+      project: "demo",
+      format: "json",
+      source_mode: "full",
+    });
   });
 
   it("builds an https GitHub deep-link with URL-encoded path segments", () => {
diff --git a/graph-ui/src/components/NodeDetailPanel.tsx b/graph-ui/src/components/NodeDetailPanel.tsx
index 54be52f36..b75d9083d 100644
--- a/graph-ui/src/components/NodeDetailPanel.tsx
+++ b/graph-ui/src/components/NodeDetailPanel.tsx
@@ -76,6 +76,8 @@ export function NodeDetailPanel({
       const res = await callTool<SnippetResult>("get_code_snippet", {
         qualified_name: node.qualified_name,
         project,
+        format: "json",
+        source_mode: "full",
       });
       setCode(res.source ?? "(source not available)");
     } catch (e) {
diff --git a/graph-ui/src/components/StatsTab.test.tsx b/graph-ui/src/components/StatsTab.test.tsx
index eb17cc715..64c44e977 100644
--- a/graph-ui/src/components/StatsTab.test.tsx
+++ b/graph-ui/src/components/StatsTab.test.tsx
@@ -12,7 +12,7 @@ function mockProjectsFetch(extra?: (url: string, init?: RequestInit) => Response
     if (overridden) return overridden;
     if (url === "/rpc") {
       return new Response(JSON.stringify({
-        result: { content: [{ text: JSON.stringify({ projects: [] }) }] },
+        result: { content: [{ text: JSON.stringify({ projects: [], has_more: false }) }] },
       }), { status: 200, headers: { "Content-Type": "application/json" } });
     }
     if (url.startsWith("/api/ui-config")) {
@@ -221,8 +221,11 @@ describe("StatsTab index modal", () => {
                 root_path: "/repo",
                 indexed_at: "2026-01-01T00:00:00Z",
               }],
+              has_more: false,
             }
-          : { node_labels: [], edge_types: [], total_nodes: 0, total_edges: 0 };
+          : {
+              node_labels: [], edge_types: [], total_nodes: 0, total_edges: 0, has_more: false,
+            };
         return new Response(JSON.stringify({
           result: { content: [{ text: JSON.stringify(result) }] },
         }), { status: 200, headers: { "Content-Type": "application/json" } });
diff --git a/graph-ui/src/hooks/useProjects.test.tsx b/graph-ui/src/hooks/useProjects.test.tsx
new file mode 100644
index 000000000..10d36a97c
--- /dev/null
+++ b/graph-ui/src/hooks/useProjects.test.tsx
@@ -0,0 +1,86 @@
+/* @vitest-environment jsdom */
+import { renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useProjects } from "./useProjects";
+
+const callToolMock = vi.fn();
+vi.mock("../api/rpc", () => ({
+  callTool: (...args: unknown[]) => callToolMock(...args),
+}));
+
+describe("useProjects machine-readable pagination", () => {
+  beforeEach(() => callToolMock.mockReset());
+
+  it("requests JSON and merges every project and schema page", async () => {
+    callToolMock.mockImplementation(async (name: string, args: Record<string, unknown>) => {
+      if (name === "list_projects") {
+        if (args.offset === 0) {
+          return {
+            projects: [{ name: "alpha", root_path: "/alpha", indexed_at: "now" }],
+            has_more: true,
+            next_offset: 1,
+          };
+        }
+        return {
+          projects: [{ name: "beta", root_path: "/beta", indexed_at: "now" }],
+          has_more: false,
+        };
+      }
+      if (name === "get_graph_schema" && args.project === "alpha") {
+        if (args.offset === 0) {
+          return {
+            node_labels: [{ label: "Function", count: 3 }],
+            edge_types: [],
+            total_nodes: 3,
+            total_edges: 2,
+            has_more: true,
+            next_offset: 1,
+          };
+        }
+        return {
+          node_labels: [],
+          edge_types: [{ type: "CALLS", count: 2 }],
+          total_nodes: 3,
+          total_edges: 2,
+          has_more: false,
+        };
+      }
+      return {
+        node_labels: [{ label: "Class", count: 1 }],
+        edge_types: [],
+        total_nodes: 1,
+        total_edges: 0,
+        has_more: false,
+      };
+    });
+
+    const { result } = renderHook(() => useProjects());
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.projects).toHaveLength(2);
+    expect(result.current.projects[0].schema?.node_labels).toEqual([
+      { label: "Function", count: 3 },
+    ]);
+    expect(result.current.projects[0].schema?.edge_types).toEqual([
+      { type: "CALLS", count: 2 },
+    ]);
+    expect(callToolMock).toHaveBeenCalledWith("list_projects", {
+      format: "json",
+      detail: "stats",
+      limit: 500,
+      offset: 0,
+    });
+    expect(callToolMock).toHaveBeenCalledWith("list_projects", {
+      format: "json",
+      detail: "stats",
+      limit: 500,
+      offset: 1,
+    });
+    expect(callToolMock).toHaveBeenCalledWith("get_graph_schema", {
+      project: "alpha",
+      format: "json",
+      limit: 500,
+      offset: 1,
+    });
+  });
+});
diff --git a/graph-ui/src/hooks/useProjects.ts b/graph-ui/src/hooks/useProjects.ts
index 5deff5215..7ed5d7511 100644
--- a/graph-ui/src/hooks/useProjects.ts
+++ b/graph-ui/src/hooks/useProjects.ts
@@ -7,6 +7,70 @@ interface ProjectInfo {
   schema: SchemaInfo | null;
 }
 
+interface ProjectPage {
+  projects?: Project[];
+  has_more?: boolean;
+  next_offset?: number;
+}
+
+interface SchemaPage extends SchemaInfo {
+  has_more?: boolean;
+  next_offset?: number;
+}
+
+const PAGE_LIMIT = 500;
+
+function nextPageOffset(page: { has_more?: boolean; next_offset?: number }, offset: number) {
+  if (typeof page.has_more !== "boolean") {
+    throw new Error("Invalid pagination response");
+  }
+  if (!page.has_more) return null;
+  if (!Number.isInteger(page.next_offset) || page.next_offset! <= offset) {
+    throw new Error("Invalid pagination response");
+  }
+  return page.next_offset!;
+}
+
+async function fetchAllProjects(): Promise<Project[]> {
+  const projects: Project[] = [];
+  let offset = 0;
+  for (;;) {
+    const page = await callTool<ProjectPage>("list_projects", {
+      format: "json",
+      detail: "stats",
+      limit: PAGE_LIMIT,
+      offset,
+    });
+    projects.push(...(page.projects ?? []));
+    const next = nextPageOffset(page, offset);
+    if (next === null) return projects;
+    offset = next;
+  }
+}
+
+async function fetchFullSchema(project: string): Promise<SchemaInfo> {
+  const nodeLabels: SchemaInfo["node_labels"] = [];
+  const edgeTypes: SchemaInfo["edge_types"] = [];
+  let firstPage: SchemaPage | null = null;
+  let offset = 0;
+  for (;;) {
+    const page = await callTool<SchemaPage>("get_graph_schema", {
+      project,
+      format: "json",
+      limit: PAGE_LIMIT,
+      offset,
+    });
+    firstPage ??= page;
+    nodeLabels.push(...(page.node_labels ?? []));
+    edgeTypes.push(...(page.edge_types ?? []));
+    const next = nextPageOffset(page, offset);
+    if (next === null) {
+      return { ...firstPage, node_labels: nodeLabels, edge_types: edgeTypes };
+    }
+    offset = next;
+  }
+}
+
 interface UseProjectsResult {
   projects: ProjectInfo[];
   loading: boolean;
@@ -23,16 +87,13 @@ export function useProjects(): UseProjectsResult {
     setLoading(true);
     setError(null);
     try {
-      const result = await callTool<{ projects: Project[] }>("list_projects");
-      const list = result.projects ?? [];
+      const list = await fetchAllProjects();
 
       /* Fetch schema for each project */
       const infos: ProjectInfo[] = await Promise.all(
         list.map(async (p) => {
           try {
-            const schema = await callTool<SchemaInfo>("get_graph_schema", {
-              project: p.name,
-            });
+            const schema = await fetchFullSchema(p.name);
             return { project: p, schema };
           } catch {
             return { project: p, schema: null };
diff --git a/scripts/smoke-test.sh b/scripts/smoke-test.sh
index 53dc130ae..59ba1a01f 100755
--- a/scripts/smoke-test.sh
+++ b/scripts/smoke-test.sh
@@ -407,7 +407,7 @@ DUP_CHECKED=0
 for TOOL_ARGS in "search_graph --project $PROJECT --name-pattern compute" \
                  "search_code --project $PROJECT --query compute" \
                  "get_architecture --project $PROJECT" \
-                 "index_status --project $PROJECT"; do
+                 "index_status --project $PROJECT --format json"; do
   # shellcheck disable=SC2086
   ENVELOPE=$("$BINARY" cli $TOOL_ARGS --json 2>/dev/null || true)
   [ -z "$ENVELOPE" ] && continue
@@ -575,7 +575,7 @@ fi
 echo "OK: trace_path found $CALLERS caller(s) for 'compute'"
 
 # 3c: get_graph_schema — verify labels exist
-if ! SCHEMA=$(cli get_graph_schema --project "$PROJECT"); then
+if ! SCHEMA=$(cli get_graph_schema --project "$PROJECT" --format json --limit 500); then
   echo "FAIL: get_graph_schema (flag form) exited non-zero"; cat "$CLI_STDERR"; exit 1
 fi
 LABELS=$(echo "$SCHEMA" | python3 -c "import json,sys; d=json.loads(sys.stdin.read()); print(len(d.get('node_labels',[])))" 2>/dev/null || echo "0")
@@ -647,8 +647,10 @@ cyp_first_cell() {
   # $1 = query; echoes rows[0][0] (or empty). Flag form passes the query as ONE
   # argv token, so string-literal args (e.g. replace(f.name,"a","A")) and Cypher
   # metacharacters {}|=~<>" need no JSON escaping.
-  cli query_graph --project "$PROJECT" --query "$1" |
-    sed -n '/^rows: /{n;p;}' | sed 's/^  //' | sed 's/^"//;s/"$//;s/\\"/"/g'
+  cli query_graph --project "$PROJECT" --query "$1" --format json |
+    python3 -c 'import json,sys
+d=json.load(sys.stdin); rows=d.get("rows", [])
+print(rows[0][0] if rows and rows[0] else "")'
 }
 
 # labels(n) → JSON list like ["Function"]
@@ -839,7 +841,7 @@ else
 fi
 
 # B4: STDIN — piped JSON resolves; this path must NOT emit a deprecation warning.
-IM_STDIN=$(echo "{\"project\":\"$PROJECT\"}" | "$BINARY" cli get_graph_schema 2>"$CLI_STDERR")
+IM_STDIN=$(echo "{\"project\":\"$PROJECT\",\"format\":\"json\",\"limit\":500}" | "$BINARY" cli get_graph_schema 2>"$CLI_STDERR")
 if ! echo "$IM_STDIN" | python3 -c "import json,sys; d=json.loads(sys.stdin.read()); sys.exit(0 if 'node_labels' in d else 1)" 2>/dev/null; then
   echo "FAIL B4: stdin get_graph_schema did not resolve"; echo "$IM_STDIN" | head -c 300; cat "$CLI_STDERR"; exit 1
 fi
@@ -850,7 +852,7 @@ echo "OK B4: STDIN input resolves, no deprecation warning"
 
 # B5: --args-file — JSON read from a file resolves; must NOT warn deprecated.
 IM_ARGS_FILE=$(smoke_mktemp_file)
-echo "{\"project\":\"$PROJECT\"}" > "$IM_ARGS_FILE"
+echo "{\"project\":\"$PROJECT\",\"format\":\"json\",\"limit\":500}" > "$IM_ARGS_FILE"
 if ! IM_AF=$(cli get_graph_schema --args-file "$IM_ARGS_FILE"); then
   echo "FAIL B5: get_graph_schema --args-file exited non-zero"; cat "$CLI_STDERR"; rm -f "$IM_ARGS_FILE"; exit 1
 fi
diff --git a/src/cli/cli.c b/src/cli/cli.c
index e6e7762cf..f6f713d1a 100644
--- a/src/cli/cli.c
+++ b/src/cli/cli.c
@@ -304,6 +304,10 @@ void cbm_cli_set_activation_runtime_parent_for_test(const char *runtime_parent)
     g_cli_activation_runtime_parent_for_test = runtime_parent;
 }
 
+const char *cbm_cli_activation_runtime_parent_for_test(void) {
+    return g_cli_activation_runtime_parent_for_test;
+}
+
 static const char *cli_activation_action_text(cbm_daemon_runtime_activation_action_t action) {
     switch (action) {
     case CBM_DAEMON_RUNTIME_ACTIVATION_INSTALL:
@@ -12292,6 +12296,18 @@ char *cbm_cli_build_args_json(const char *tool_name, int argc, char **argv, char
     return result;
 }
 
+static void cli_print_schema_value(const yyjson_val *value) {
+    if (yyjson_is_str(value)) {
+        fputs(yyjson_get_str(value), stdout);
+        return;
+    }
+    char *json = yyjson_val_write(value, 0, NULL);
+    if (json) {
+        fputs(json, stdout);
+        free(json);
+    }
+}
+
 int cbm_cli_print_tool_help(const char *tool_name) {
     const char *schema_str = cbm_mcp_tool_input_schema(tool_name);
     if (!schema_str) {
@@ -12322,6 +12338,8 @@ int cbm_cli_print_tool_help(const char *tool_name) {
             }
             const char *type = "string";
             const char *desc = "";
+            yyjson_val *choices = NULL;
+            yyjson_val *default_value = NULL;
             if (yyjson_is_obj(pval)) {
                 yyjson_val *t = yyjson_obj_get(pval, "type");
                 if (t && yyjson_is_str(t)) {
@@ -12331,12 +12349,36 @@ int cbm_cli_print_tool_help(const char *tool_name) {
                 if (d && yyjson_is_str(d)) {
                     desc = yyjson_get_str(d);
                 }
+                choices = yyjson_obj_get(pval, "enum");
+                default_value = yyjson_obj_get(pval, "default");
             }
             char flag[CLI_BUF_256];
             snprintf(flag, sizeof(flag), "%s", name);
             cli_snake_to_kebab(flag);
             bool req = cli_schema_required_has(required, name);
-            printf("  --%s <%s>%s", flag, type, req ? " [required]" : "");
+            printf("  --%s <", flag);
+            if (choices && yyjson_is_arr(choices) && yyjson_arr_size(choices) > 0) {
+                size_t idx;
+                size_t max;
+                yyjson_val *choice;
+                yyjson_arr_foreach(choices, idx, max, choice) {
+                    if (idx > 0) {
+                        fputc('|', stdout);
+                    }
+                    cli_print_schema_value(choice);
+                }
+            } else {
+                fputs(type, stdout);
+            }
+            fputc('>', stdout);
+            if (req) {
+                fputs(" [required]", stdout);
+            }
+            if (default_value) {
+                fputs(" [default: ", stdout);
+                cli_print_schema_value(default_value);
+                fputc(']', stdout);
+            }
             if (desc[0]) {
                 printf("  %s", desc);
             }
diff --git a/src/cli/cli.h b/src/cli/cli.h
index db5e13979..c435b6aee 100644
--- a/src/cli/cli.h
+++ b/src/cli/cli.h
@@ -454,6 +454,7 @@ void cbm_cli_set_activation_ops_for_test(const cbm_cli_activation_ops_t *ops);
  * private runtime parent. NULL restores the platform default. This is not a
  * command-line or environment override. */
 void cbm_cli_set_activation_runtime_parent_for_test(const char *runtime_parent);
+const char *cbm_cli_activation_runtime_parent_for_test(void);
 
 /* ── Subcommands (wired from main.c) ─────────────────────────── */
 
diff --git a/src/cli/hook_augment.c b/src/cli/hook_augment.c
index 73ad1c45b..185533e2d 100644
--- a/src/cli/hook_augment.c
+++ b/src/cli/hook_augment.c
@@ -26,6 +26,7 @@
 
 #include <ctype.h>
 #include <stdbool.h>
+#include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -44,6 +45,7 @@
 #define HA_MIN_TOKEN 4            /* skip short/noisy patterns before any work */
 #define HA_MAX_TOKEN 96
 #define HA_RESULT_LIMIT 5
+#define HA_LIST_PAGE_LIMIT 500
 #define HA_METADATA_CAP 192
 #define HA_MAX_WALKUP 8    /* cwd may be a subdir of the indexed root  */
 #define HA_DEADLINE_MS 300 /* hard in-process budget (see also: the    */
@@ -488,11 +490,45 @@ static char *ha_coverage_context(const char *envelope, const char *rel, bool *is
         strcmp(status, "invalid_path") != 0) {
         const char *kind = NULL;
         const char *detail = NULL;
+        char *range_detail = NULL;
         yyjson_val *coverage = yyjson_obj_get(item, "coverage");
         yyjson_val *row = coverage && yyjson_is_arr(coverage) ? yyjson_arr_get(coverage, 0) : NULL;
         if (row) {
             kind = ha_obj_str(row, "kind");
             detail = ha_obj_str(row, "detail");
+            yyjson_val *ranges = yyjson_obj_get(row, "ranges");
+            size_t range_count = ranges && yyjson_is_arr(ranges) ? yyjson_arr_size(ranges) : 0;
+            if ((!detail || !detail[0]) && range_count > 0 && range_count <= SIZE_MAX / 48U) {
+                range_detail = calloc(range_count * 48U + 1U, 1U);
+                if (range_detail) {
+                    size_t used = 0;
+                    size_t index;
+                    size_t maximum;
+                    yyjson_val *range;
+                    yyjson_arr_foreach(ranges, index, maximum, range) {
+                        yyjson_val *start_value = yyjson_obj_get(range, "start");
+                        yyjson_val *end_value = yyjson_obj_get(range, "end");
+                        if (!yyjson_is_int(start_value) || !yyjson_is_int(end_value)) {
+                            continue;
+                        }
+                        long long start = (long long)yyjson_get_sint(start_value);
+                        long long end = (long long)yyjson_get_sint(end_value);
+                        int written =
+                            start == end
+                                ? snprintf(range_detail + used, range_count * 48U + 1U - used,
+                                           "%s%lld", used ? "," : "", start)
+                                : snprintf(range_detail + used, range_count * 48U + 1U - used,
+                                           "%s%lld-%lld", used ? "," : "", start, end);
+                        if (written < 0 || (size_t)written >= range_count * 48U + 1U - used) {
+                            free(range_detail);
+                            range_detail = NULL;
+                            break;
+                        }
+                        used += (size_t)written;
+                    }
+                    detail = range_detail;
+                }
+            }
         }
         text = malloc(1536);
         if (text) {
@@ -519,6 +555,7 @@ static char *ha_coverage_context(const char *envelope, const char *rel, bool *is
                          status, freshness ? freshness : "unavailable");
             }
         }
+        free(range_detail);
     }
     yyjson_doc_free(idoc);
     yyjson_doc_free(edoc);
@@ -588,6 +625,7 @@ static char *ha_resolve_coverage(cbm_mcp_server_t *srv, const char *file_path) {
     yyjson_mut_obj_add_str(adoc, aroot, "project", project);
     yyjson_mut_arr_add_strcpy(adoc, paths, rel);
     yyjson_mut_obj_add_val(adoc, aroot, "paths", paths);
+    yyjson_mut_obj_add_str(adoc, aroot, "format", "json");
     char *args = yyjson_mut_write(adoc, 0, NULL);
     yyjson_mut_doc_free(adoc);
     free(project);
@@ -788,53 +826,108 @@ static char *ha_registry_project_for_path(cbm_mcp_server_t *srv, const char *cwd
     if (!ha_canonical_path(cwd, canonical_cwd, sizeof(canonical_cwd))) {
         return NULL;
     }
-    char *envelope = cbm_mcp_handle_tool(srv, "list_projects", "{\"metadata_only\":true}");
-    yyjson_doc *doc = envelope ? yyjson_read(envelope, strlen(envelope), 0) : NULL;
-    free(envelope);
-    if (!doc) {
-        return NULL;
-    }
-    yyjson_val *outer = yyjson_doc_get_root(doc);
-    yyjson_val *error = yyjson_obj_get(outer, "isError");
-    yyjson_val *structured = yyjson_obj_get(outer, "structuredContent");
-    yyjson_val *projects = structured ? yyjson_obj_get(structured, "projects") : NULL;
-    if ((error && yyjson_is_true(error)) || !projects || !yyjson_is_arr(projects)) {
-        yyjson_doc_free(doc);
-        return NULL;
-    }
-
-    const char *best_name = NULL;
+    char *best_name = NULL;
     char best_root[4096] = {0};
     size_t best_length = 0U;
-    size_t index;
-    size_t maximum;
-    yyjson_val *project;
-    yyjson_arr_foreach(projects, index, maximum, project) {
-        const char *name = ha_obj_str(project, "name");
-        const char *root = ha_obj_str(project, "root_path");
-        char canonical_root[4096];
-        if (!name || !name[0] || !root || !root[0] ||
-            !ha_canonical_path(root, canonical_root, sizeof(canonical_root)) ||
-            !ha_path_contains(canonical_root, canonical_cwd)) {
-            continue;
+    int64_t offset = 0;
+    bool complete = false;
+
+    for (;;) {
+        char args[160];
+        int written = snprintf(args, sizeof(args),
+                               "{\"metadata_only\":true,\"format\":\"json\",\"limit\":%d,"
+                               "\"offset\":%lld}",
+                               HA_LIST_PAGE_LIMIT, (long long)offset);
+        if (written < 0 || (size_t)written >= sizeof(args)) {
+            break;
         }
-        size_t length = strlen(canonical_root);
-        if (length > best_length) {
-            best_name = name;
-            best_length = length;
-            snprintf(best_root, sizeof(best_root), "%s", canonical_root);
+        char *envelope = cbm_mcp_handle_tool(srv, "list_projects", args);
+        yyjson_doc *edoc = envelope ? yyjson_read(envelope, strlen(envelope), 0) : NULL;
+        free(envelope);
+        if (!edoc) {
+            break;
         }
+        yyjson_val *outer = yyjson_doc_get_root(edoc);
+        yyjson_val *error = yyjson_obj_get(outer, "isError");
+        yyjson_val *content = yyjson_obj_get(outer, "content");
+        yyjson_val *item0 = content && yyjson_is_arr(content) ? yyjson_arr_get(content, 0) : NULL;
+        const char *inner = ha_obj_str(item0, "text");
+        yyjson_doc *idoc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+        if ((error && yyjson_is_true(error)) || !idoc) {
+            if (idoc) {
+                yyjson_doc_free(idoc);
+            }
+            yyjson_doc_free(edoc);
+            break;
+        }
+        yyjson_val *root = yyjson_doc_get_root(idoc);
+        yyjson_val *projects = yyjson_obj_get(root, "projects");
+        if (!projects || !yyjson_is_arr(projects)) {
+            yyjson_doc_free(idoc);
+            yyjson_doc_free(edoc);
+            break;
+        }
+
+        size_t index;
+        size_t maximum;
+        yyjson_val *project;
+        yyjson_arr_foreach(projects, index, maximum, project) {
+            const char *name = ha_obj_str(project, "name");
+            const char *project_root = ha_obj_str(project, "root_path");
+            char canonical_root[4096];
+            if (!name || !name[0] || !project_root || !project_root[0] ||
+                !ha_canonical_path(project_root, canonical_root, sizeof(canonical_root)) ||
+                !ha_path_contains(canonical_root, canonical_cwd)) {
+                continue;
+            }
+            size_t length = strlen(canonical_root);
+            if (length > best_length) {
+                char *candidate = strdup(name);
+                if (!candidate) {
+                    continue;
+                }
+                free(best_name);
+                best_name = candidate;
+                best_length = length;
+                snprintf(best_root, sizeof(best_root), "%s", canonical_root);
+            }
+        }
+
+        yyjson_val *has_more = yyjson_obj_get(root, "has_more");
+        if (!has_more || !yyjson_is_bool(has_more)) {
+            yyjson_doc_free(idoc);
+            yyjson_doc_free(edoc);
+            break;
+        }
+        bool more = yyjson_is_true(has_more);
+        if (!more) {
+            complete = true;
+            yyjson_doc_free(idoc);
+            yyjson_doc_free(edoc);
+            break;
+        }
+        yyjson_val *next = yyjson_obj_get(root, "next_offset");
+        int64_t next_offset = next && yyjson_is_int(next) ? yyjson_get_int(next) : -1;
+        yyjson_doc_free(idoc);
+        yyjson_doc_free(edoc);
+        if (next_offset <= offset) {
+            break;
+        }
+        offset = next_offset;
     }
-    char *result = best_name ? strdup(best_name) : NULL;
-    if (result && root_out && root_out_size > 0U) {
+
+    if (!complete) {
+        free(best_name);
+        return NULL;
+    }
+    if (best_name && root_out && root_out_size > 0U) {
         int written = snprintf(root_out, root_out_size, "%s", best_root);
         if (written < 0 || (size_t)written >= root_out_size) {
-            free(result);
-            result = NULL;
+            free(best_name);
+            best_name = NULL;
         }
     }
-    yyjson_doc_free(doc);
-    return result;
+    return best_name;
 }
 
 /* Return the nearest indexed graph project for cwd. Probe derived names first
@@ -855,6 +948,7 @@ static char *ha_resolve_indexed_project_with_root(cbm_mcp_server_t *srv, const c
             if (doc && root) {
                 yyjson_mut_doc_set_root(doc, root);
                 yyjson_mut_obj_add_str(doc, root, "project", project);
+                yyjson_mut_obj_add_str(doc, root, "format", "json");
                 char *args = yyjson_mut_write(doc, 0, NULL);
                 yyjson_mut_doc_free(doc);
                 if (args) {
diff --git a/src/cli/progress_sink.c b/src/cli/progress_sink.c
index 7f1e69425..d994c8a81 100644
--- a/src/cli/progress_sink.c
+++ b/src/cli/progress_sink.c
@@ -31,6 +31,9 @@ static FILE *s_out;
 static atomic_int s_needs_newline;
 static int s_gbuf_nodes = NOT_SET;
 static int s_gbuf_edges = NOT_SET;
+static CBMLogLevel s_previous_log_level = CBM_LOG_WARN;
+static bool s_raised_log_level;
+static bool s_preserve_details;
 static cbm_mutex_t s_sink_mutex;
 static atomic_int s_sink_mutex_state = ATOMIC_VAR_INIT(LOCK_UNINITIALIZED);
 
@@ -47,8 +50,69 @@ static void progress_sink_mutex_ensure(void) {
     while (atomic_load_explicit(&s_sink_mutex_state, memory_order_acquire) != LOCK_READY) {}
 }
 
-bool cbm_cli_progress_enabled(bool explicitly_requested, bool stderr_is_tty) {
-    return explicitly_requested || stderr_is_tty;
+bool cbm_cli_output_flags_parse(int *argc, char **argv, cbm_cli_output_flags_t *flags, char *error,
+                                size_t error_size) {
+    if (!argc || !argv || !flags) {
+        return false;
+    }
+    memset(flags, 0, sizeof(*flags));
+    if (error && error_size > 0) {
+        error[0] = '\0';
+    }
+
+    /* --quiet and --progress are reserved process controls wherever they
+     * appear, matching the existing --progress behavior. --verbose remains
+     * outer-only because tools such as index_status own a verbose input. */
+    bool before_tool = true;
+    int output_index = 0;
+    for (int input_index = 0; input_index < *argc; input_index++) {
+        char *arg = argv[input_index];
+        bool quiet = arg && strcmp(arg, "--quiet") == 0;
+        bool progress = arg && strcmp(arg, "--progress") == 0;
+        bool verbose = before_tool && arg && strcmp(arg, "--verbose") == 0;
+        if (quiet) {
+            flags->quiet_requested = true;
+        } else if (progress) {
+            flags->progress_requested = true;
+        } else if (verbose) {
+            flags->verbose_requested = true;
+        } else {
+            argv[output_index++] = arg;
+            if (before_tool && arg && arg[0] != '-') {
+                before_tool = false;
+            }
+        }
+    }
+    *argc = output_index;
+
+    if (flags->quiet_requested && (flags->progress_requested || flags->verbose_requested)) {
+        if (error && error_size > 0) {
+            (void)snprintf(error, error_size,
+                           "--quiet cannot be combined with --progress or outer --verbose; "
+                           "use --quiet for errors-only stderr, --progress for lifecycle "
+                           "feedback, or --verbose for informational diagnostics");
+        }
+        return false;
+    }
+    return true;
+}
+
+void cbm_cli_diagnostics_configure(bool quiet_requested, bool verbose_requested) {
+    if (quiet_requested) {
+        /* Keep ERROR records visible while suppressing DEBUG/INFO/WARN. An
+         * explicit CBM_LOG_LEVEL=none remains stronger than --quiet. */
+        if (cbm_log_get_level() < CBM_LOG_ERROR) {
+            cbm_log_set_level(CBM_LOG_ERROR);
+        }
+        return;
+    }
+    if (verbose_requested && cbm_log_get_level() > CBM_LOG_INFO) {
+        cbm_log_set_level(CBM_LOG_INFO);
+    }
+}
+
+bool cbm_cli_progress_enabled(bool explicitly_requested, bool quiet_requested, bool stderr_is_tty) {
+    return !quiet_requested && (explicitly_requested || stderr_is_tty);
 }
 
 static void progress_tool_name(const char *tool_name, char out[CBM_SZ_64]) {
@@ -184,6 +248,14 @@ void cbm_progress_sink_init(FILE *out) {
     atomic_store(&s_needs_newline, 0);
     s_gbuf_nodes = NOT_SET;
     s_gbuf_edges = NOT_SET;
+    s_previous_log_level = cbm_log_get_level();
+    s_preserve_details = s_previous_log_level <= CBM_LOG_INFO;
+    s_raised_log_level = s_previous_log_level > CBM_LOG_INFO;
+    if (s_raised_log_level) {
+        /* Progress is an explicit INFO opt-in. The replacement sink below
+         * keeps only recognized lifecycle events plus warnings/errors. */
+        cbm_log_set_level(CBM_LOG_INFO);
+    }
     cbm_log_set_sink(cbm_progress_sink_fn);
     cbm_mutex_unlock(&s_sink_mutex);
 }
@@ -197,6 +269,11 @@ void cbm_progress_sink_fini(void) {
         (void)fflush(s_out);
     }
     s_out = NULL;
+    if (s_raised_log_level) {
+        cbm_log_set_level(s_previous_log_level);
+        s_raised_log_level = false;
+    }
+    s_preserve_details = false;
     cbm_mutex_unlock(&s_sink_mutex);
 }
 
@@ -338,6 +415,20 @@ static const event_handler_t handlers[] = {
 
 enum { HANDLER_COUNT = sizeof(handlers) / sizeof(handlers[0]) };
 
+/* The progress sink replaces normal logger output. Preserve actionable
+ * failures verbatim and, when INFO/DEBUG was already selected before progress
+ * initialization, preserve unrecognized diagnostic lines as well. Logger
+ * callbacks do not include a trailing newline. */
+static void passthrough_line(const char *line) {
+    flush_carriage();
+    (void)fputs(line, s_out);
+    size_t line_len = strlen(line);
+    if (line_len == 0 || line[line_len - 1] != '\n') {
+        (void)fputc('\n', s_out);
+    }
+    (void)fflush(s_out);
+}
+
 void cbm_progress_sink_fn(const char *line) {
     progress_sink_mutex_ensure();
     cbm_mutex_lock(&s_sink_mutex);
@@ -345,6 +436,28 @@ void cbm_progress_sink_fn(const char *line) {
         cbm_mutex_unlock(&s_sink_mutex);
         return;
     }
+    char level[CBM_SZ_32] = {0};
+    if (!extract_kv(line, "level", level, (int)sizeof(level))) {
+        cbm_mutex_unlock(&s_sink_mutex);
+        return;
+    }
+    if (strcmp(level, "warn") == 0 || strcmp(level, "error") == 0) {
+        passthrough_line(line);
+        cbm_mutex_unlock(&s_sink_mutex);
+        return;
+    }
+    if (strcmp(level, "debug") == 0) {
+        if (s_preserve_details) {
+            passthrough_line(line);
+        }
+        cbm_mutex_unlock(&s_sink_mutex);
+        return;
+    }
+    if (strcmp(level, "info") != 0) {
+        cbm_mutex_unlock(&s_sink_mutex);
+        return;
+    }
+
     char msg[CBM_SZ_64] = {0};
     if (!extract_kv(line, "msg", msg, (int)sizeof(msg))) {
         cbm_mutex_unlock(&s_sink_mutex);
@@ -357,5 +470,8 @@ void cbm_progress_sink_fn(const char *line) {
             return;
         }
     }
+    if (s_preserve_details) {
+        passthrough_line(line);
+    }
     cbm_mutex_unlock(&s_sink_mutex);
 }
diff --git a/src/cli/progress_sink.h b/src/cli/progress_sink.h
index 7301a3357..7a9058b8a 100644
--- a/src/cli/progress_sink.h
+++ b/src/cli/progress_sink.h
@@ -3,7 +3,7 @@
  *
  * Installs a log sink that maps structured pipeline events to phase labels.
  * Interactive terminals enable it automatically; --progress forces it when
- * stderr is redirected.
+ * stderr is redirected, and --quiet disables it.
  * Usage:
  *   cbm_progress_sink_init(stderr);
  *   // ... run pipeline ...
@@ -13,12 +13,27 @@
 #define CBM_PROGRESS_SINK_H
 
 #include <stdbool.h>
+#include <stddef.h>
 #include <stdint.h>
 #include <stdio.h>
 
+typedef struct {
+    bool quiet_requested;
+    bool progress_requested;
+    bool verbose_requested;
+} cbm_cli_output_flags_t;
+
+/* Parse process-level output controls without consuming a tool's own
+ * `--verbose` argument. The argv array is compacted in place. */
+bool cbm_cli_output_flags_parse(int *argc, char **argv, cbm_cli_output_flags_t *flags, char *error,
+                                size_t error_size);
+
+/* Apply process-level diagnostic verbosity without changing stdout. */
+void cbm_cli_diagnostics_configure(bool quiet_requested, bool verbose_requested);
+
 /* Interactive terminals get lifecycle feedback automatically. --progress
- * forces the same behavior for redirected stderr without touching stdout. */
-bool cbm_cli_progress_enabled(bool explicitly_requested, bool stderr_is_tty);
+ * forces the same behavior for redirected stderr; --quiet disables both. */
+bool cbm_cli_progress_enabled(bool explicitly_requested, bool quiet_requested, bool stderr_is_tty);
 void cbm_cli_progress_start(FILE *out, const char *tool_name);
 void cbm_cli_progress_finish(FILE *out, const char *tool_name, bool success, uint64_t elapsed_ms);
 
diff --git a/src/cypher/cypher.c b/src/cypher/cypher.c
index b84eb59c0..2229fc0ce 100644
--- a/src/cypher/cypher.c
+++ b/src/cypher/cypher.c
@@ -7,6 +7,7 @@
  */
 #include "cypher/cypher.h"
 #include "foundation/compat.h"
+#include "foundation/constants.h"
 #include "store/store.h"
 #include "foundation/platform.h"
 #include "foundation/limits.h"
@@ -2834,6 +2835,9 @@ static void rb_add_row(result_builder_t *rb, const char **values) {
 
 static _Thread_local uint64_t g_cypher_deadline_ms = 0; /* absolute; 0 = disarmed */
 static _Thread_local bool g_cypher_timed_out = false;
+/* Sticky for one cbm_cypher_execute call. Unlike row_count, this survives caps
+ * that happen before DISTINCT, aggregation, ORDER BY, or the final projection. */
+static _Thread_local bool g_cypher_truncated = false;
 static _Thread_local int64_t g_cypher_deadline_override_ms = -1; /* test hook; <0 = default */
 
 static void cypher_deadline_arm(void) {
@@ -3084,6 +3088,9 @@ static void scan_pattern_nodes(cbm_store_t *store, const char *project, int max_
                                       .limit = max_rows * CYP_GROWTH_10};
         cbm_search_output_t sout = {0};
         cbm_store_search(store, &params, &sout);
+        if (sout.total > sout.count) {
+            g_cypher_truncated = true;
+        }
         *out_count = sout.count;
         *out_nodes = malloc(sout.count * sizeof(cbm_node_t));
         for (int i = 0; i < sout.count; i++) {
@@ -3163,6 +3170,8 @@ static void process_edges(cbm_store_t *store, cbm_edge_t *edges, int edge_count,
                 binding_set_edge(&nb, rel_var, &edges[ei]);
             }
             new_bindings[(*new_count)++] = nb;
+        } else {
+            g_cypher_truncated = true;
         }
         node_fields_free(&found);
     }
@@ -3186,6 +3195,7 @@ static void expand_var_length(cbm_store_t *store, cbm_rel_pattern_t *rel,
      * clamp — never a silent truncation. */
     int depth_cap = cbm_cypher_max_depth();
     int max_depth = rel->max_hops > 0 ? rel->max_hops : depth_cap;
+    bool probe_beyond_depth_cap = rel->max_hops <= 0 || max_depth > depth_cap;
     if (max_depth > depth_cap) {
         char req_buf[16];
         char cap_buf[16];
@@ -3197,12 +3207,26 @@ static void expand_var_length(cbm_store_t *store, cbm_rel_pattern_t *rel,
     }
     cbm_traverse_result_t tr = {0};
     const char *dir = rel->direction ? rel->direction : "outbound";
-    cbm_store_bfs(store, src->id, dir, rel->types, rel->type_count, max_depth, CBM_PERCENT, &tr);
+    /* Probe one row and, when the hop range is engine-capped, one depth beyond
+     * the historical ceilings. Processing still uses the original bounds, so
+     * output behavior is preserved while actual saturation becomes observable. */
+    int traversal_depth = probe_beyond_depth_cap ? depth_cap + SKIP_ONE : max_depth;
+    cbm_store_bfs(store, src->id, dir, rel->types, rel->type_count, traversal_depth,
+                  CBM_PERCENT + SKIP_ONE, &tr);
+    int visited_count = tr.visited_count;
+    if (visited_count > CBM_PERCENT) {
+        g_cypher_truncated = true;
+        visited_count = CBM_PERCENT;
+    }
     /* Same contract as process_edges: the budget caps materialisation, never
      * detection, so a saturated source cannot report match_count == 0 and get a
      * fabricated OPTIONAL "no match" row. */
-    for (int v = 0; v < tr.visited_count; v++) {
+    for (int v = 0; v < visited_count; v++) {
         cbm_node_hop_t *hop = &tr.visited[v];
+        if (hop->hop > max_depth) {
+            g_cypher_truncated = true;
+            continue;
+        }
         if (hop->hop < rel->min_hops) {
             continue;
         }
@@ -3218,6 +3242,8 @@ static void expand_var_length(cbm_store_t *store, cbm_rel_pattern_t *rel,
             binding_copy(&nb, b);
             binding_set(&nb, to_var, &hop->node);
             new_bindings[(*new_count)++] = nb;
+        } else {
+            g_cypher_truncated = true;
         }
     }
     cbm_store_traverse_free(&tr);
@@ -3439,7 +3465,8 @@ static void rb_apply_order_by(result_builder_t *rb, const cbm_return_clause_t *r
     }
 }
 
-static void rb_apply_skip_limit(result_builder_t *rb, int skip_n, int limit) {
+static void rb_apply_skip_limit(result_builder_t *rb, int skip_n, int limit,
+                                bool limit_is_engine_budget) {
     /* Skip */
     if (skip_n > 0 && skip_n < rb->row_count) {
         for (int i = 0; i < skip_n; i++) {
@@ -3461,6 +3488,9 @@ static void rb_apply_skip_limit(result_builder_t *rb, int skip_n, int limit) {
     }
     /* Limit */
     if (limit >= 0 && rb->row_count > limit) {
+        if (limit_is_engine_budget) {
+            g_cypher_truncated = true;
+        }
         for (int i = limit; i < rb->row_count; i++) {
             for (int c = 0; c < rb->col_count; c++) {
                 safe_str_free(&rb->rows[i][c]);
@@ -3704,6 +3734,25 @@ static const char *project_item(binding_t *b, cbm_return_item_t *item, char *fun
     if (is_scalar_value_func(item->func)) {
         return apply_string_func(item->func, raw, func_buf, buf_sz);
     }
+    /* Direct node/edge fields live in the binding until this row has been
+     * copied by rb_add_row. Keep those allocation-backed values intact: the
+     * fixed per-column scratch buffer exists only to stabilize computed and
+     * JSON-derived rotating-buffer values. Copying every value through it
+     * silently clipped long qualified names and paths to 511 bytes before the
+     * MCP response budget or prefix directory ever saw them. */
+    for (int i = 0; raw && raw[0] && i < b->var_count; i++) {
+        const cbm_node_t *node = &b->var_nodes[i];
+        if (raw == node->project || raw == node->label || raw == node->name ||
+            raw == node->qualified_name || raw == node->file_path || raw == node->properties_json) {
+            return raw;
+        }
+    }
+    for (int i = 0; raw && raw[0] && i < b->edge_var_count; i++) {
+        const cbm_edge_t *edge = &b->edge_vars[i];
+        if (raw == edge->project || raw == edge->type || raw == edge->properties_json) {
+            return raw;
+        }
+    }
     /* Copy into the caller's per-column buffer. `raw` may point to node_prop's
      * rotating scratch buffer, which the next column's projection would overwrite
      * before rb_add_row copies the assembled row — aliasing every such column to
@@ -4149,14 +4198,22 @@ static void execute_with_clause(cbm_query_t *q, binding_t **bindings_ptr, int *b
 static int collect_pattern_vars(cbm_query_t *q, const char **vars, int max_vars) {
     int vc = 0;
     for (int pi = 0; pi < q->pattern_count; pi++) {
-        for (int ni = 0; ni < q->patterns[pi].node_count && vc < max_vars; ni++) {
+        for (int ni = 0; ni < q->patterns[pi].node_count; ni++) {
             if (q->patterns[pi].nodes[ni].variable) {
-                vars[vc++] = q->patterns[pi].nodes[ni].variable;
+                if (vc < max_vars) {
+                    vars[vc++] = q->patterns[pi].nodes[ni].variable;
+                } else {
+                    g_cypher_truncated = true;
+                }
             }
         }
-        for (int ri = 0; ri < q->patterns[pi].rel_count && vc < max_vars; ri++) {
+        for (int ri = 0; ri < q->patterns[pi].rel_count; ri++) {
             if (q->patterns[pi].rels[ri].variable) {
-                vars[vc++] = q->patterns[pi].rels[ri].variable;
+                if (vc < max_vars) {
+                    vars[vc++] = q->patterns[pi].rels[ri].variable;
+                } else {
+                    g_cypher_truncated = true;
+                }
             }
         }
     }
@@ -4213,11 +4270,22 @@ static void execute_return_star(cbm_query_t *q, binding_t *bindings, int bind_co
     const char *vars[CBM_SZ_32];
     int vc = collect_pattern_vars(q, vars, CBM_SZ_32);
     build_star_columns(rb, vars, vc);
-    for (int bi = 0; bi < bind_count && rb->row_count < max_rows; bi++) {
+    int projection_cap = max_rows;
+    bool cap_is_engine_budget = true;
+    cbm_return_clause_t *ret = q->ret;
+    if (ret && ret->limit >= 0 && ret->limit <= max_rows && !ret->distinct &&
+        ret->order_key_count == 0 && ret->skip <= 0) {
+        projection_cap = ret->limit;
+        cap_is_engine_budget = false;
+    }
+    for (int bi = 0; bi < bind_count && rb->row_count < projection_cap; bi++) {
         const char *vals[CBM_SZ_128];
         project_star_row(&bindings[bi], vars, vc, vals);
         rb_add_row(rb, vals);
     }
+    if (cap_is_engine_budget && bind_count > projection_cap) {
+        g_cypher_truncated = true;
+    }
 }
 
 /* Format an aggregate value into buf based on function name */
@@ -4463,8 +4531,10 @@ static void build_return_columns(result_builder_t *rb, cbm_return_clause_t *ret)
 static void execute_return_simple(cbm_return_clause_t *ret, binding_t *bindings, int bind_count,
                                   int max_rows, result_builder_t *rb) {
     int proj_cap = max_rows;
-    if (ret->limit > 0 && !ret->distinct && ret->order_key_count == 0 && ret->skip <= 0) {
+    bool cap_is_engine_budget = true;
+    if (ret->limit >= 0 && !ret->distinct && ret->order_key_count == 0 && ret->skip <= 0) {
         proj_cap = ret->limit;
+        cap_is_engine_budget = false;
     }
     for (int bi = 0; bi < bind_count && rb->row_count < proj_cap; bi++) {
         const char *vals[CBM_SZ_32];
@@ -4475,6 +4545,9 @@ static void execute_return_simple(cbm_return_clause_t *ret, binding_t *bindings,
         }
         rb_add_row(rb, vals);
     }
+    if (cap_is_engine_budget && bind_count > proj_cap) {
+        g_cypher_truncated = true;
+    }
 }
 
 /* Build default 3-column headers (name, qualified_name, label) per variable */
@@ -4501,9 +4574,13 @@ static void execute_default_projection(cbm_pattern_t *pat0, binding_t *bindings,
                                        int max_rows, result_builder_t *rb) {
     const char *vars[CYP_MAX_VARS];
     int vc = 0;
-    for (int ni = 0; ni < pat0->node_count && vc < CYP_MAX_VARS; ni++) {
+    for (int ni = 0; ni < pat0->node_count; ni++) {
         if (pat0->nodes[ni].variable) {
-            vars[vc++] = pat0->nodes[ni].variable;
+            if (vc < CYP_MAX_VARS) {
+                vars[vc++] = pat0->nodes[ni].variable;
+            } else {
+                g_cypher_truncated = true;
+            }
         }
     }
     build_default_columns(rb, vars, vc);
@@ -4518,6 +4595,9 @@ static void execute_default_projection(cbm_pattern_t *pat0, binding_t *bindings,
         }
         rb_add_row(rb, vals);
     }
+    if (bind_count > max_rows) {
+        g_cypher_truncated = true;
+    }
 }
 
 /* Worst-case binding_t slot count for a node cross-join: one row per
@@ -4714,6 +4794,8 @@ static void expand_from_bound_terminal(cbm_store_t *store, cbm_pattern_t *patn,
                             binding_set_edge(&nb, rel->variable, &edges[ei]);
                         }
                         new_bindings[new_count++] = nb;
+                    } else {
+                        g_cypher_truncated = true;
                     }
                     node_fields_free(&found);
                 }
@@ -4816,7 +4898,9 @@ static void execute_return_clause(cbm_query_t *q, cbm_return_clause_t *ret, bind
         rb_apply_distinct(rb);
     }
     rb_apply_order_by(rb, ret);
-    rb_apply_skip_limit(rb, ret->skip, ret->limit >= 0 ? ret->limit : max_rows);
+    bool limit_is_engine_budget = ret->limit < 0;
+    rb_apply_skip_limit(rb, ret->skip, limit_is_engine_budget ? max_rows : ret->limit,
+                        limit_is_engine_budget);
 }
 
 static int execute_single(cbm_store_t *store, cbm_query_t *q, const char *project, int max_rows,
@@ -4894,6 +4978,7 @@ int cbm_cypher_execute(cbm_store_t *store, const char *query, const char *projec
                        cbm_cypher_result_t *out) {
     memset(out, 0, sizeof(*out));
     g_cypher_depth_clamped = 0;
+    g_cypher_truncated = false;
     cypher_deadline_arm(); /* #601: start the wall-clock budget for this query */
     if (max_rows <= 0) {
         max_rows = CYPHER_RESULT_CEILING;
@@ -4910,6 +4995,7 @@ int cbm_cypher_execute(cbm_store_t *store, const char *query, const char *projec
     if (execute_single(store, q, project, max_rows, &rb) < 0) {
         rb_free(&rb);
         cbm_query_free(q);
+        out->truncated = g_cypher_truncated;
         out->error = heap_strdup("query aborted: out of memory or an allocation limit was reached");
         return CBM_NOT_FOUND;
     }
@@ -4922,6 +5008,7 @@ int cbm_cypher_execute(cbm_store_t *store, const char *query, const char *projec
             rb_free(&rb);
             rb_free(&rb2);
             cbm_query_free(q);
+            out->truncated = g_cypher_truncated;
             out->error =
                 heap_strdup("query aborted: out of memory or an allocation limit was reached");
             return CBM_NOT_FOUND;
@@ -4945,6 +5032,7 @@ int cbm_cypher_execute(cbm_store_t *store, const char *query, const char *projec
     if (g_cypher_timed_out) {
         rb_free(&rb);
         cbm_query_free(q);
+        out->truncated = g_cypher_truncated;
         out->error =
             heap_strdup("query exceeded the execution time limit — narrow the pattern with a WHERE "
                         "filter, use a directed MATCH instead of an unbounded OPTIONAL MATCH, or "
@@ -4954,8 +5042,10 @@ int cbm_cypher_execute(cbm_store_t *store, const char *query, const char *projec
 
     /* Check ceiling */
     if (rb.row_count >= CYPHER_RESULT_CEILING) {
+        g_cypher_truncated = true;
         rb_free(&rb);
         cbm_query_free(q);
+        out->truncated = true;
         out->error = heap_strdup("result exceeded 100k rows — use narrower filters or add LIMIT");
         return CBM_NOT_FOUND;
     }
@@ -4964,6 +5054,7 @@ int cbm_cypher_execute(cbm_store_t *store, const char *query, const char *projec
     out->col_count = rb.col_count;
     out->rows = rb.rows;
     out->row_count = rb.row_count;
+    out->truncated = g_cypher_truncated;
     if (g_cypher_depth_clamped > 0) {
         char wbuf[CBM_SZ_256];
         snprintf(wbuf, sizeof(wbuf),
diff --git a/src/cypher/cypher.h b/src/cypher/cypher.h
index a1e4462ab..9e66b56ec 100644
--- a/src/cypher/cypher.h
+++ b/src/cypher/cypher.h
@@ -321,6 +321,10 @@ typedef struct {
     /* rows[row_idx][col_idx] = string value */
     const char ***rows;
     int row_count;
+    /* True when an internal row/candidate ceiling prevented exhaustive
+     * evaluation. A Cypher LIMIT is part of query semantics and does not set
+     * this flag by itself. */
+    bool truncated;
     /* Non-NULL when the query was rejected (e.g. result too large) */
     char *error;
     /* Non-NULL advisory (caller-visible, not an error): e.g. a variable-
diff --git a/src/foundation/compat_fs.c b/src/foundation/compat_fs.c
index 692813c20..f3be067b4 100644
--- a/src/foundation/compat_fs.c
+++ b/src/foundation/compat_fs.c
@@ -123,17 +123,20 @@ cbm_dirent_t *cbm_readdir(cbm_dir_t *d) {
 
 int cbm_path_info_utf8(const char *path, cbm_path_info_t *out) {
     if (!path || !out) {
-        return CBM_NOT_FOUND;
+        return CBM_PATH_INFO_UNAVAILABLE;
     }
     wchar_t *wpath = cbm_path_to_wide(path);
     if (!wpath) {
-        return CBM_NOT_FOUND;
+        return CBM_PATH_INFO_UNAVAILABLE;
     }
     WIN32_FILE_ATTRIBUTE_DATA data;
     BOOL ok = GetFileAttributesExW(wpath, GetFileExInfoStandard, &data);
+    DWORD path_error = ok ? ERROR_SUCCESS : GetLastError();
     free(wpath);
     if (!ok) {
-        return CBM_NOT_FOUND;
+        return path_error == ERROR_FILE_NOT_FOUND || path_error == ERROR_PATH_NOT_FOUND
+                   ? CBM_PATH_INFO_ABSENT
+                   : CBM_PATH_INFO_UNAVAILABLE;
     }
     memset(out, 0, sizeof(*out));
     out->is_directory = (data.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) != 0;
@@ -154,7 +157,7 @@ int cbm_path_info_utf8(const char *path, cbm_path_info_t *out) {
         written >= windows_to_unix_ticks
             ? (int64_t)((written - windows_to_unix_ticks) * NANOSECONDS_PER_WINDOWS_TICK)
             : 0;
-    return 0;
+    return CBM_PATH_INFO_OK;
 }
 
 void cbm_closedir(cbm_dir_t *d) {
@@ -795,11 +798,12 @@ cbm_dirent_t *cbm_readdir(cbm_dir_t *d) {
 
 int cbm_path_info_utf8(const char *path, cbm_path_info_t *out) {
     if (!path || !out) {
-        return CBM_NOT_FOUND;
+        return CBM_PATH_INFO_UNAVAILABLE;
     }
     struct stat state;
     if (lstat(path, &state) != 0) {
-        return CBM_NOT_FOUND;
+        return errno == ENOENT || errno == ENOTDIR ? CBM_PATH_INFO_ABSENT
+                                                   : CBM_PATH_INFO_UNAVAILABLE;
     }
     memset(out, 0, sizeof(*out));
     out->is_regular = S_ISREG(state.st_mode);
@@ -813,7 +817,7 @@ int cbm_path_info_utf8(const char *path, cbm_path_info_t *out) {
     out->mtime_ns =
         ((int64_t)state.st_mtim.tv_sec * INT64_C(1000000000)) + (int64_t)state.st_mtim.tv_nsec;
 #endif
-    return 0;
+    return CBM_PATH_INFO_OK;
 }
 
 void cbm_closedir(cbm_dir_t *d) {
diff --git a/src/foundation/compat_fs.h b/src/foundation/compat_fs.h
index 240ebceae..8f0d16388 100644
--- a/src/foundation/compat_fs.h
+++ b/src/foundation/compat_fs.h
@@ -36,7 +36,15 @@ typedef struct {
     int64_t mtime_ns;
 } cbm_path_info_t;
 
-/* Returns 0 on success and -1 when the path cannot be inspected. */
+enum {
+    CBM_PATH_INFO_OK = 0,
+    CBM_PATH_INFO_UNAVAILABLE = -1,
+    CBM_PATH_INFO_ABSENT = -2,
+};
+
+/* Distinguishes a proven absent path from permission, encoding, and transient
+ * inspection failures. Existing callers that only test zero/nonzero retain
+ * their behavior. */
 int cbm_path_info_utf8(const char *path, cbm_path_info_t *out);
 
 /* Open a directory for iteration. Returns NULL on error. */
diff --git a/src/foundation/log.c b/src/foundation/log.c
index 5b0b86007..0eb82078d 100644
--- a/src/foundation/log.c
+++ b/src/foundation/log.c
@@ -23,7 +23,7 @@
  * Relaxed ordering is the right level: each is an independent scalar with no
  * happens-before relationship to publish alongside it, and the log path must
  * stay cheap enough that nobody is tempted to route around it. */
-static _Atomic CBMLogLevel g_log_level = CBM_LOG_INFO;
+static _Atomic CBMLogLevel g_log_level = CBM_LOG_WARN;
 static _Atomic CBMLogFormat g_log_format = CBM_LOG_FORMAT_TEXT;
 /* Cast, not bare NULL: NULL is ((void*)0) and the implicit void*-to-
  * function-pointer conversion is not a compile-time constant, which
@@ -87,6 +87,14 @@ parse_format:;
      * silently change the operator-selected output shape. */
 }
 
+void cbm_log_init_for_process(bool quiet_by_default, bool require_info_liveness) {
+    cbm_log_set_level(quiet_by_default ? CBM_LOG_WARN : CBM_LOG_INFO);
+    cbm_log_init_from_env();
+    if (require_info_liveness && cbm_log_get_level() > CBM_LOG_INFO) {
+        cbm_log_set_level(CBM_LOG_INFO);
+    }
+}
+
 void cbm_log_set_sink(cbm_log_sink_fn fn) {
     cbm_log_set_sink_ex(fn, CBM_LOG_SINK_REPLACE);
 }
diff --git a/src/foundation/log.h b/src/foundation/log.h
index baad71d14..f5e75447d 100644
--- a/src/foundation/log.h
+++ b/src/foundation/log.h
@@ -44,7 +44,14 @@ typedef enum {
  * unchanged. Call once at startup before any threads or log lines. */
 void cbm_log_init_from_env(void);
 
-/* Set minimum log level (default: INFO). */
+/* Apply a role-aware startup policy, then the environment override. Thin
+ * frontends pass quiet_by_default=true; detached daemons pass false. Physical
+ * workers also pass require_info_liveness=true because their private log is
+ * the supervisor's no-progress heartbeat, so WARN/NONE cannot suppress INFO
+ * lifecycle records and turn a healthy long index into a false hang. */
+void cbm_log_init_for_process(bool quiet_by_default, bool require_info_liveness);
+
+/* Set minimum log level (raw process default: WARN; startup policy is role-aware). */
 void cbm_log_set_level(CBMLogLevel level);
 
 /* Get current log level. */
diff --git a/src/main.c b/src/main.c
index 574002b6a..d68dff6b1 100644
--- a/src/main.c
+++ b/src/main.c
@@ -6,6 +6,8 @@
  *   cli <tool> <json>  Run a single tool call and print result
  *   --version       Print version and exit
  *   --help          Print usage and exit
+ *   cli --quiet     Show errors only; disable automatic terminal progress
+ *   cli --verbose   Include informational logs for one-shot commands
  *   --ui=true/false Enable/disable HTTP UI server (persisted)
  *   --port=N        Set HTTP UI port (persisted, default 9749)
  *   --tool-profile=analysis|scout  Expose a restricted agent tool surface
@@ -533,7 +535,13 @@ static bool client_start_parent_watchdog(pid_t initial_ppid) {
 
 /* ── CLI mode ───────────────────────────────────────────────────── */
 
-#define CLI_USAGE "Usage: codebase-memory-mcp cli [--progress] [--json] <tool_name> [json_args]\n"
+#define CLI_USAGE                                                                             \
+    "Usage: codebase-memory-mcp cli [--quiet] [--progress] [--verbose] [--json] <tool_name> " \
+    "[json_args]\n"                                                                           \
+    "  --quiet     Show errors only; cannot combine with --progress or outer --verbose\n"     \
+    "  --progress  Show lifecycle progress even when stderr is redirected\n"                  \
+    "  --verbose   Include informational logs (preserves CBM_LOG_LEVEL=debug)\n"              \
+    "  --json      Print the raw MCP result envelope\n"
 
 /* Extract text content from MCP tool result envelope and print it.
  * MCP results: {"content":[{"type":"text","text":"..."}],"isError":...}
@@ -659,10 +667,21 @@ static bool cli_first_nonspace_is_brace(const char *s) {
     return *s == '{';
 }
 
-static char *main_local_cli_daemon_execute(const char *tool_name, const char *args_json);
+static char *main_local_cli_daemon_execute(const char *tool_name, const char *args_json,
+                                           bool quiet_requested);
 
 static int run_cli(int argc, char **argv, cbm_project_lock_manager_t *project_locks,
                    main_local_maintenance_context_t *maintenance_context) {
+    cbm_cli_output_flags_t output_flags;
+    char output_error[CBM_SZ_512] = {0};
+    if (!cbm_cli_output_flags_parse(&argc, argv, &output_flags, output_error,
+                                    sizeof(output_error))) {
+        (void)fprintf(stderr, "error: %s\n",
+                      output_error[0] ? output_error : "invalid output mode");
+        (void)fprintf(stderr, CLI_USAGE);
+        return SKIP_ONE;
+    }
+    cbm_cli_diagnostics_configure(output_flags.quiet_requested, output_flags.verbose_requested);
     if (argc == 1 && argv && (strcmp(argv[0], "--help") == 0 || strcmp(argv[0], "-h") == 0)) {
         (void)fputs(CLI_USAGE, stdout);
         return 0;
@@ -672,7 +691,6 @@ static int run_cli(int argc, char **argv, cbm_project_lock_manager_t *project_lo
         return SKIP_ONE;
     }
 
-    bool progress_requested = cli_strip_flag(&argc, argv, "--progress");
     bool raw_json = cli_strip_flag(&argc, argv, "--json");
 
     /* Supervisor worker role: when this process was spawned as a supervised index
@@ -740,11 +758,13 @@ static int run_cli(int argc, char **argv, cbm_project_lock_manager_t *project_lo
     } else if (rem_argc >= SKIP_ONE && cli_first_nonspace_is_brace(rem_argv[0])) {
         /* raw-JSON back-compat: cli <tool> '{"k":"v"}' (deprecated path). Warn on
          * STDERR only — stdout must stay clean JSON for piping. */
-        (void)fprintf(stderr,
-                      "warning: passing raw JSON to 'cli %s' is deprecated and "
-                      "will be removed in a future release; use flags (run 'cli "
-                      "%s --help'), --args-file <path>, or piped stdin.\n",
-                      tool_name, tool_name);
+        if (!output_flags.quiet_requested) {
+            (void)fprintf(stderr,
+                          "warning: passing raw JSON to 'cli %s' is deprecated and "
+                          "will be removed in a future release; use flags (run 'cli "
+                          "%s --help'), --args-file <path>, or piped stdin.\n",
+                          tool_name, tool_name);
+        }
         args_json = rem_argv[0];
     } else if (rem_argc >= SKIP_ONE && strncmp(rem_argv[0], "--", 2) == 0) {
         /* flag form: cli <tool> --flag value --bare-bool ... */
@@ -769,7 +789,8 @@ static int run_cli(int argc, char **argv, cbm_project_lock_manager_t *project_lo
     }
 
     bool progress =
-        !index_worker && cbm_cli_progress_enabled(progress_requested, cli_isatty(2) != 0);
+        !index_worker && cbm_cli_progress_enabled(output_flags.progress_requested,
+                                                  output_flags.quiet_requested, cli_isatty(2) != 0);
     uint64_t progress_started_ms = cbm_now_ms();
     if (progress) {
         cbm_progress_sink_init(stderr);
@@ -789,7 +810,7 @@ static int run_cli(int argc, char **argv, cbm_project_lock_manager_t *project_lo
     bool maintenance_binding_failed = false;
     bool maintenance_cancelled = false;
     if (!index_worker) {
-        result = main_local_cli_daemon_execute(tool_name, args_json);
+        result = main_local_cli_daemon_execute(tool_name, args_json, output_flags.quiet_requested);
     } else {
         srv = cbm_mcp_server_new(NULL);
         if (srv) {
@@ -890,7 +911,8 @@ static void print_help(void) {
     printf("codebase-memory-mcp %s\n\n", CBM_VERSION);
     printf("Usage:\n");
     printf("  codebase-memory-mcp              Run MCP server on stdio\n");
-    printf("  codebase-memory-mcp cli [--progress] [--json] <tool> [args]\n");
+    printf("  codebase-memory-mcp cli [--quiet] [--progress] [--verbose] [--json] <tool> "
+           "[args]\n");
     printf("                                      Run one tool locally, then exit\n");
     printf("  codebase-memory-mcp install [-y|-n] [--force] [--dry-run] "
            "[--dir=<path>] [--skip-config]\n");
@@ -899,6 +921,12 @@ static void print_help(void) {
     printf("  codebase-memory-mcp config <list|get|set|reset>\n");
     printf("  codebase-memory-mcp --version    Print version\n");
     printf("  codebase-memory-mcp --help       Print this help\n");
+    printf("\nCLI output options:\n");
+    printf("  --quiet       Show errors only; disable automatic terminal progress\n");
+    printf("  --progress    Show lifecycle progress even with redirected stderr\n");
+    printf("  --verbose     Include informational diagnostics\n");
+    printf("  --json        Print the raw MCP result envelope\n");
+    printf("  --quiet cannot be combined with --progress or outer --verbose.\n");
     printf("\nUI options:\n");
     printf("  --ui=true    Enable HTTP graph visualization (persisted)\n");
     printf("  --ui=false   Disable HTTP graph visualization (persisted)\n");
@@ -1275,15 +1303,23 @@ static cbm_daemon_ipc_endpoint_t *main_daemon_endpoint_new(void) {
     return cbm_daemon_bootstrap_endpoint_new(runtime_parent);
 }
 
-static bool main_local_cli_feedback_enabled(int argc, char **argv) {
-    bool requested = false;
+static bool main_cli_flag_present(int argc, char **argv, const char *flag) {
+    if (!argv || !flag) {
+        return false;
+    }
     for (int index = 1; index < argc; index++) {
-        if (argv[index] && strcmp(argv[index], "--progress") == 0) {
-            requested = true;
-            break;
+        if (argv[index] && strcmp(argv[index], flag) == 0) {
+            return true;
         }
     }
-    return cbm_cli_progress_enabled(requested, cli_isatty(2) != 0);
+    return false;
+}
+
+static bool main_local_cli_feedback_enabled(int argc, char **argv) {
+    bool requested = false;
+    requested = main_cli_flag_present(argc, argv, "--progress");
+    bool quiet = main_cli_flag_present(argc, argv, "--quiet");
+    return cbm_cli_progress_enabled(requested, quiet, cli_isatty(2) != 0);
 }
 
 static int main_local_transition_acquire(const cbm_daemon_ipc_endpoint_t *endpoint, FILE *feedback,
@@ -1488,7 +1524,8 @@ static void main_report_client_bootstrap_failure(cbm_daemon_process_role_t role,
  * lifecycle used to, instead of deadlocking behind the pinned daemon. Same-
  * or newer-build daemons and dev builds are never auto-drained. */
 static cbm_daemon_bootstrap_status_t main_client_bootstrap_with_upgrade(
-    const cbm_daemon_bootstrap_config_t *config, cbm_daemon_bootstrap_result_t *result) {
+    const cbm_daemon_bootstrap_config_t *config, cbm_daemon_bootstrap_result_t *result,
+    bool report_lifecycle) {
     cbm_daemon_bootstrap_status_t status = cbm_daemon_bootstrap_execute(config, result);
     if (status != CBM_DAEMON_BOOTSTRAP_CONFLICT) {
         return status;
@@ -1500,11 +1537,13 @@ static cbm_daemon_bootstrap_status_t main_client_bootstrap_with_upgrade(
         !main_semver_newer(config->identity->semantic_version, active.semantic_version)) {
         return status;
     }
-    (void)fprintf(stderr,
-                  "codebase-memory-mcp: retiring the active permanent daemon (%s, pid %lu) for "
-                  "this newer build (%s)\n",
-                  active.semantic_version, (unsigned long)active.daemon_pid,
-                  config->identity->semantic_version);
+    if (report_lifecycle) {
+        (void)fprintf(stderr,
+                      "codebase-memory-mcp: retiring the active permanent daemon (%s, pid %lu) "
+                      "for this newer build (%s)\n",
+                      active.semantic_version, (unsigned long)active.daemon_pid,
+                      config->identity->semantic_version);
+    }
     cbm_daemon_runtime_activation_result_t drain;
     if (!cbm_daemon_runtime_request_activation_shutdown(config->endpoint, config->identity,
                                                         CBM_DAEMON_RUNTIME_ACTIVATION_UPDATE,
@@ -1521,8 +1560,9 @@ static cbm_daemon_bootstrap_status_t main_client_bootstrap_with_upgrade(
  * sessions and hooks: an active daemon (any starter) is recycled, an absent
  * one is spawned for this command — with a hint that `daemon start` removes
  * that per-command cost. Only supervised index workers stay in-process. */
-static char *main_local_cli_daemon_execute(const char *tool_name, const char *args_json) {
-    cbm_daemon_ipc_endpoint_t *endpoint = cbm_daemon_bootstrap_endpoint_new(NULL);
+static char *main_local_cli_daemon_execute(const char *tool_name, const char *args_json,
+                                           bool quiet_requested) {
+    cbm_daemon_ipc_endpoint_t *endpoint = main_daemon_endpoint_new();
     char executable_path[MAIN_PATH_CAP] = {0};
     cbm_daemon_build_identity_t identity;
     bool prepared =
@@ -1543,7 +1583,8 @@ static char *main_local_cli_daemon_execute(const char *tool_name, const char *ar
         .startup_timeout_ms = MAIN_MCP_STARTUP_TIMEOUT_MS,
     };
     cbm_daemon_bootstrap_result_t bootstrap;
-    cbm_daemon_bootstrap_status_t status = main_client_bootstrap_with_upgrade(&config, &bootstrap);
+    cbm_daemon_bootstrap_status_t status =
+        main_client_bootstrap_with_upgrade(&config, &bootstrap, !quiet_requested);
     cbm_daemon_ipc_endpoint_free(endpoint);
     if (status != CBM_DAEMON_BOOTSTRAP_CONNECTED || !bootstrap.client) {
         (void)fprintf(stderr, "error: %s\n",
@@ -1552,9 +1593,10 @@ static char *main_local_cli_daemon_execute(const char *tool_name, const char *ar
         return NULL;
     }
     if (bootstrap.daemon_spawned) {
-        (void)fprintf(stderr, "hint: this command started a temporary CBM daemon. "
-                              "`codebase-memory-mcp daemon start` keeps one warm and removes this "
-                              "startup cost from every CLI command.\n");
+        /* Routine cold-start advice is informational. Default one-shot CLI
+         * output stays pipe-clean; `cli --verbose ...` opts into this detail. */
+        cbm_log_info("cli.daemon.spawned", "hint",
+                     "codebase-memory-mcp daemon start keeps one warm");
     }
     char session_root[MAIN_PATH_CAP];
     char allowed_root[MAIN_PATH_CAP];
@@ -2309,7 +2351,7 @@ static int main_run_daemon_ctl(int argc, char **argv, const cbm_daemon_ipc_endpo
     };
     cbm_daemon_bootstrap_result_t start_result;
     cbm_daemon_bootstrap_status_t start_status =
-        main_client_bootstrap_with_upgrade(&start_config, &start_result);
+        main_client_bootstrap_with_upgrade(&start_config, &start_result, true);
     if (start_status != CBM_DAEMON_BOOTSTRAP_CONNECTED || !start_result.client) {
         (void)fprintf(stderr, "error: %s\n",
                       start_result.message[0] ? start_result.message
@@ -2395,7 +2437,17 @@ int main(int argc, char **argv) {
 
     cbm_cli_set_version(CBM_VERSION);
     cbm_profile_init();
-    cbm_log_init_from_env();
+    /* The raw logger starts WARN so allocator setup cannot pollute protocol or
+     * CLI output before argv is classified. Detached daemons retain INFO
+     * lifecycle records; physical workers require INFO because those records
+     * are their supervisor's quiet-timeout heartbeat. */
+    bool quiet_log_default = role != CBM_DAEMON_PROCESS_DAEMON && role != CBM_DAEMON_PROCESS_WORKER;
+    cbm_log_init_for_process(quiet_log_default, role == CBM_DAEMON_PROCESS_WORKER);
+    if (role == CBM_DAEMON_PROCESS_LOCAL_CLI && main_cli_flag_present(argc, argv, "--quiet")) {
+        /* Apply quiet before local coordination begins, not only once tool
+         * dispatch is reached, so pre-dispatch WARN chatter is suppressed. */
+        cbm_cli_diagnostics_configure(true, false);
+    }
 
     cbm_mcp_tool_profile_t tool_profile = CBM_MCP_TOOL_PROFILE_ALL;
     if (role == CBM_DAEMON_PROCESS_MCP_CLIENT &&
@@ -2435,7 +2487,7 @@ int main(int argc, char **argv) {
             (void)fputs("Preparing one-shot local CBM command...\n", feedback);
             (void)fflush(feedback);
         }
-        cbm_daemon_ipc_endpoint_t *local_endpoint = cbm_daemon_bootstrap_endpoint_new(NULL);
+        cbm_daemon_ipc_endpoint_t *local_endpoint = main_daemon_endpoint_new();
         char local_executable[MAIN_PATH_CAP];
         cbm_daemon_build_identity_t local_identity;
         cbm_project_lock_manager_t *project_locks =
@@ -2595,7 +2647,7 @@ int main(int argc, char **argv) {
                           cbm_index_worker_argv_status_message(worker_status));
             return EXIT_FAILURE;
         }
-        cbm_daemon_ipc_endpoint_t *worker_endpoint = cbm_daemon_bootstrap_endpoint_new(NULL);
+        cbm_daemon_ipc_endpoint_t *worker_endpoint = main_daemon_endpoint_new();
         cbm_project_lock_manager_t *worker_project_locks =
             worker_endpoint ? cbm_project_lock_manager_new(worker_endpoint) : NULL;
         cbm_version_cohort_manager_t *worker_cohort_manager =
@@ -2834,7 +2886,7 @@ int main(int argc, char **argv) {
     };
     cbm_daemon_bootstrap_result_t bootstrap_result;
     cbm_daemon_bootstrap_status_t bootstrap_status =
-        main_client_bootstrap_with_upgrade(&bootstrap_config, &bootstrap_result);
+        main_client_bootstrap_with_upgrade(&bootstrap_config, &bootstrap_result, true);
     cbm_daemon_ipc_endpoint_free(endpoint);
     if (bootstrap_status != CBM_DAEMON_BOOTSTRAP_CONNECTED || !bootstrap_result.client) {
         main_report_client_bootstrap_failure(role, &bootstrap_result);
diff --git a/src/mcp/compact_out.c b/src/mcp/compact_out.c
index 2d8bef364..2fbbb8314 100644
--- a/src/mcp/compact_out.c
+++ b/src/mcp/compact_out.c
@@ -5,6 +5,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#include <yyjson/yyjson.h>
 
 enum { SB_INITIAL_CAP = 1024 };
 
@@ -75,20 +76,20 @@ void cbm_sb_free(cbm_sb_t *sb) {
 /* ── Tree quoting ────────────────────────────────────────────────── */
 
 /* True when `s` parses as an integer or real literal (sign, digits, one dot). */
-static bool looks_numeric(const char *s) {
-    if (!s || !*s) {
+static bool looks_numeric_n(const char *s, size_t len) {
+    if (!s || len == 0) {
         return false;
     }
-    const char *p = s;
-    if (*p == '-' || *p == '+') {
-        p++;
+    size_t offset = 0;
+    if (s[offset] == '-' || s[offset] == '+') {
+        offset++;
     }
     bool digit = false;
     bool dot = false;
-    for (; *p; p++) {
-        if (isdigit((unsigned char)*p)) {
+    for (; offset < len; offset++) {
+        if (isdigit((unsigned char)s[offset])) {
             digit = true;
-        } else if (*p == '.' && !dot) {
+        } else if (s[offset] == '.' && !dot) {
             dot = true;
         } else {
             return false;
@@ -98,10 +99,12 @@ static bool looks_numeric(const char *s) {
 }
 
 /* UTF-8 sequence length starting at p, validating continuation bytes and the
- * lead-byte ranges (RFC 3629: no overlongs, no surrogates, max U+10FFFF);
- * 0 = not a valid sequence start. Reads stop at the first invalid byte, so a
- * terminating NUL is never overrun. */
-static size_t utf8_sequence_length(const unsigned char *p) {
+ * lead-byte ranges (RFC 3629: no overlongs, no surrogates, max U+10FFFF).
+ * `remaining` makes truncated multibyte input safe to inspect. */
+static size_t utf8_sequence_length(const unsigned char *p, size_t remaining) {
+    if (!p || remaining == 0) {
+        return 0;
+    }
     unsigned char c = p[0];
     if (c < 0x80) {
         return 1;
@@ -110,9 +113,12 @@ static size_t utf8_sequence_length(const unsigned char *p) {
         return 0; /* bare continuation byte or overlong lead */
     }
     if (c < 0xE0) {
-        return (p[1] & 0xC0) == 0x80 ? 2 : 0;
+        return remaining >= 2 && (p[1] & 0xC0) == 0x80 ? 2 : 0;
     }
     if (c < 0xF0) {
+        if (remaining < 3) {
+            return 0;
+        }
         unsigned char lo = c == 0xE0 ? 0xA0 : 0x80;
         unsigned char hi = c == 0xED ? 0x9F : 0xBF;
         if (p[1] < lo || p[1] > hi || (p[2] & 0xC0) != 0x80) {
@@ -121,6 +127,9 @@ static size_t utf8_sequence_length(const unsigned char *p) {
         return 3;
     }
     if (c < 0xF5) {
+        if (remaining < 4) {
+            return 0;
+        }
         unsigned char lo = c == 0xF0 ? 0x90 : 0x80;
         unsigned char hi = c == 0xF4 ? 0x8F : 0xBF;
         if (p[1] < lo || p[1] > hi || (p[2] & 0xC0) != 0x80 || (p[3] & 0xC0) != 0x80) {
@@ -131,38 +140,126 @@ static size_t utf8_sequence_length(const unsigned char *p) {
     return 0;
 }
 
-static bool needs_quotes(const char *s) {
-    if (!s || !*s) {
+static bool output_text_requires_encoding(const char *data, size_t len) {
+    static const char bytes_prefix[] = "@bytes:";
+    static const char utf8_prefix[] = "@utf8:";
+    if (!data) {
+        return len != 0;
+    }
+    if ((len >= sizeof(bytes_prefix) - 1 &&
+         memcmp(data, bytes_prefix, sizeof(bytes_prefix) - 1) == 0) ||
+        (len >= sizeof(utf8_prefix) - 1 &&
+         memcmp(data, utf8_prefix, sizeof(utf8_prefix) - 1) == 0)) {
+        return true;
+    }
+    size_t offset = 0;
+    while (offset < len) {
+        size_t sequence = utf8_sequence_length((const unsigned char *)data + offset, len - offset);
+        if (!sequence) {
+            return true;
+        }
+        offset += sequence;
+    }
+    return false;
+}
+
+bool cbm_output_encode_text(const char *data, size_t len, char **encoded, size_t *encoded_len) {
+    static const char bytes_prefix[] = "@bytes:";
+    static const char utf8_prefix[] = "@utf8:";
+    static const char hex[] = "0123456789abcdef";
+    if (!encoded || !encoded_len || (!data && len != 0)) {
+        return false;
+    }
+    *encoded = NULL;
+    *encoded_len = len;
+    if (!output_text_requires_encoding(data, len)) {
+        return true;
+    }
+
+    bool valid_utf8 = true;
+    size_t offset = 0;
+    while (valid_utf8 && offset < len) {
+        size_t sequence = utf8_sequence_length((const unsigned char *)data + offset, len - offset);
+        if (!sequence) {
+            valid_utf8 = false;
+            break;
+        }
+        offset += sequence;
+    }
+
+    size_t prefix_len = valid_utf8 ? sizeof(utf8_prefix) - 1 : sizeof(bytes_prefix) - 1;
+    size_t payload_len = len;
+    if (!valid_utf8) {
+        if (len > ((size_t)-1 - prefix_len - 1) / 2) {
+            return false;
+        }
+        payload_len = len * 2;
+    } else if (len > (size_t)-1 - prefix_len - 1) {
+        return false;
+    }
+    char *out = (char *)malloc(prefix_len + payload_len + 1);
+    if (!out) {
+        return false;
+    }
+    memcpy(out, valid_utf8 ? utf8_prefix : bytes_prefix, prefix_len);
+    if (valid_utf8) {
+        if (len > 0) {
+            memcpy(out + prefix_len, data, len);
+        }
+    } else {
+        for (size_t i = 0; i < len; i++) {
+            unsigned char byte = (unsigned char)data[i];
+            out[prefix_len + i * 2] = hex[byte >> 4];
+            out[prefix_len + i * 2 + 1] = hex[byte & 0x0f];
+        }
+    }
+    *encoded_len = prefix_len + payload_len;
+    out[*encoded_len] = '\0';
+    *encoded = out;
+    return true;
+}
+
+static bool needs_quotes_n(const char *s, size_t len) {
+    if (!s || len == 0) {
         return false; /* empty cells emit as the "-" placeholder, not quotes */
     }
-    for (const char *p = s; *p; p++) {
-        unsigned char c = (unsigned char)*p;
+    size_t offset = 0;
+    while (offset < len) {
+        unsigned char c = (unsigned char)s[offset];
         /* Space-delimited rows: any internal whitespace or quote forces
          * quoting so column positions stay parseable. Control bytes and
          * invalid UTF-8 force the quoted path too, which sanitizes them —
          * one raw byte otherwise makes line-oriented consumers (BSD grep)
          * treat the ENTIRE tool output as unmatchable binary. */
-        if (isspace(c) || *p == '"' || *p == '\r' || c < 0x20 || c == 0x7f) {
+        if (isspace(c) || s[offset] == '"' || s[offset] == '\r' || c < 0x20 || c == 0x7f) {
             return true;
         }
         if (c >= 0x80) {
-            size_t len = utf8_sequence_length((const unsigned char *)p);
-            if (!len) {
+            size_t sequence = utf8_sequence_length((const unsigned char *)s + offset, len - offset);
+            if (!sequence) {
                 return true;
             }
-            p += len - 1;
+            offset += sequence;
+        } else {
+            offset++;
         }
     }
-    if (strcmp(s, "true") == 0 || strcmp(s, "false") == 0 || strcmp(s, "null") == 0 ||
-        strcmp(s, "-") == 0) {
+    if ((len == 4 && memcmp(s, "true", 4) == 0) || (len == 5 && memcmp(s, "false", 5) == 0) ||
+        (len == 4 && memcmp(s, "null", 4) == 0) || (len == 1 && s[0] == '-')) {
         return true;
     }
-    return looks_numeric(s);
+    return looks_numeric_n(s, len);
 }
 
-static void append_quoted(cbm_sb_t *sb, const char *s) {
+static bool needs_quotes(const char *s) {
+    return needs_quotes_n(s, s ? strlen(s) : 0);
+}
+
+static void append_quoted_n(cbm_sb_t *sb, const char *s, size_t len) {
     cbm_sb_append_n(sb, "\"", 1);
-    for (const char *p = s ? s : ""; *p; p++) {
+    size_t offset = 0;
+    while (s && offset < len) {
+        const char *p = s + offset;
         switch (*p) {
         case '"':
             cbm_sb_append_n(sb, "\\\"", 2);
@@ -186,39 +283,89 @@ static void append_quoted(cbm_sb_t *sb, const char *s) {
                 snprintf(esc, sizeof(esc), "\\u%04x", (unsigned)c);
                 cbm_sb_append(sb, esc);
             } else {
-                size_t len = utf8_sequence_length((const unsigned char *)p);
-                if (len) {
-                    cbm_sb_append_n(sb, p, len);
-                    p += len - 1;
+                size_t sequence = utf8_sequence_length((const unsigned char *)p, len - offset);
+                if (sequence) {
+                    cbm_sb_append_n(sb, p, sequence);
+                    offset += sequence;
+                    continue;
                 } else {
-                    /* Invalid byte → U+FFFD: output is valid UTF-8 by
-                     * construction, and the corruption stays visible. */
-                    cbm_sb_append_n(sb, "\xEF\xBF\xBD", 3);
+                    /* Callers normalize first; retain a defensive printable
+                     * escape if an internal caller ever violates that rule. */
+                    char esc[8];
+                    snprintf(esc, sizeof(esc), "\\u%04x", (unsigned)c);
+                    cbm_sb_append(sb, esc);
                 }
             }
             break;
         }
         }
+        offset++;
     }
     cbm_sb_append_n(sb, "\"", 1);
 }
 
-static void append_value(cbm_sb_t *sb, const char *s) {
-    if (!s || !*s) {
+static void append_quoted(cbm_sb_t *sb, const char *s) {
+    append_quoted_n(sb, s, s ? strlen(s) : 0);
+}
+
+static void append_value_n(cbm_sb_t *sb, const char *s, size_t len) {
+    if (!s || len == 0) {
         cbm_sb_append_n(sb, "-", 1); /* stable column positions for empties */
         return;
     }
-    if (needs_quotes(s)) {
-        append_quoted(sb, s);
+    char *encoded = NULL;
+    size_t encoded_len = 0;
+    if (!cbm_output_encode_text(s, len, &encoded, &encoded_len)) {
+        sb->oom = true;
+        return;
+    }
+    const char *safe = encoded ? encoded : s;
+    size_t safe_len = encoded ? encoded_len : len;
+    if (needs_quotes_n(safe, safe_len)) {
+        append_quoted_n(sb, safe, safe_len);
+    } else {
+        cbm_sb_append_n(sb, safe, safe_len);
+    }
+    free(encoded);
+}
+
+static void append_value(cbm_sb_t *sb, const char *s) {
+    append_value_n(sb, s, s ? strlen(s) : 0);
+}
+
+/* Object keys and table column names share the compact tree's structural
+ * line. Keep common identifier-like names bare, but quote anything that can
+ * be confused with a delimiter or escape sequence. Unlike a value cell, an
+ * empty key must remain the lossless string "" rather than the missing-value
+ * placeholder "-". */
+static void append_key_n(cbm_sb_t *sb, const char *s, size_t len) {
+    const char *raw = s ? s : "";
+    char *encoded = NULL;
+    size_t encoded_len = 0;
+    if (!cbm_output_encode_text(raw, len, &encoded, &encoded_len)) {
+        sb->oom = true;
+        return;
+    }
+    const char *safe = encoded ? encoded : raw;
+    size_t safe_len = encoded ? encoded_len : len;
+    if (safe_len == 0 || needs_quotes_n(safe, safe_len) || memchr(safe, ':', safe_len) ||
+        memchr(safe, '(', safe_len) || memchr(safe, ')', safe_len) ||
+        memchr(safe, '\\', safe_len)) {
+        append_quoted_n(sb, safe, safe_len);
     } else {
-        cbm_sb_append(sb, s);
+        cbm_sb_append_n(sb, safe, safe_len);
     }
+    free(encoded);
+}
+
+static void append_key(cbm_sb_t *sb, const char *s) {
+    append_key_n(sb, s, s ? strlen(s) : 0);
 }
 
 /* ── Scalars ────────────────────────────────────────────────────── */
 
 void cbm_tree_scalar_str(cbm_sb_t *sb, const char *key, const char *val) {
-    cbm_sb_append(sb, key);
+    append_key(sb, key);
     cbm_sb_append_n(sb, ": ", 2);
     append_value(sb, val);
     cbm_sb_append_n(sb, "\n", 1);
@@ -227,14 +374,14 @@ void cbm_tree_scalar_str(cbm_sb_t *sb, const char *key, const char *val) {
 void cbm_tree_scalar_int(cbm_sb_t *sb, const char *key, long long v) {
     char num[32];
     snprintf(num, sizeof(num), "%lld", v);
-    cbm_sb_append(sb, key);
+    append_key(sb, key);
     cbm_sb_append_n(sb, ": ", 2);
     cbm_sb_append(sb, num);
     cbm_sb_append_n(sb, "\n", 1);
 }
 
 void cbm_tree_scalar_bool(cbm_sb_t *sb, const char *key, bool v) {
-    cbm_sb_append(sb, key);
+    append_key(sb, key);
     cbm_sb_append_n(sb, ": ", 2);
     cbm_sb_append(sb, v ? "true" : "false");
     cbm_sb_append_n(sb, "\n", 1);
@@ -248,11 +395,11 @@ void cbm_tree_table_header(cbm_sb_t *sb, const char *key, int n, const char *con
                            int ncols) {
     char num[32];
     snprintf(num, sizeof(num), ": %d  (cols:", n);
-    cbm_sb_append(sb, key);
+    append_key(sb, key);
     cbm_sb_append(sb, num);
     for (int i = 0; i < ncols; i++) {
         cbm_sb_append_n(sb, " ", 1);
-        cbm_sb_append(sb, cols[i]);
+        append_key(sb, cols[i]);
     }
     cbm_sb_append_n(sb, ")\n", 2);
 }
@@ -296,3 +443,761 @@ void cbm_tree_cell_bool(cbm_sb_t *sb, bool v, bool first) {
 void cbm_tree_row_end(cbm_sb_t *sb) {
     cbm_sb_append_n(sb, "\n", 1);
 }
+
+/* ── Response-local prefix directories ─────────────────────────── */
+
+enum {
+    TREE_PREFIX_MIN_LEN = 12,
+    TREE_PREFIX_MIN_USES = 3,
+    TREE_PREFIX_MIN_SAVING = 64,
+    TREE_PREFIX_MIN_PERCENT = 15,
+    TREE_PREFIX_MIN_TOKEN_SHAPE_PERCENT = 1,
+    TREE_PREFIX_MAX_REFS = 16,
+    TREE_PREFIX_MAX_SEEDS = 1024,
+    TREE_PREFIX_MAX_CANDIDATES = 512,
+    TREE_PREFIX_MAX_CELLS = 8192,
+    TREE_PREFIX_MAX_LEN = 16 * 1024,
+};
+
+typedef struct {
+    char *text;
+    size_t len;
+    size_t uses;
+    size_t score;
+    int id;
+    bool active;
+} tree_prefix_candidate_t;
+
+/* A dependency-free lower-resolution proxy for modern tokenizer pre-splits.
+ * It deliberately undercounts words (camelCase and Unicode stay whole), while
+ * counting punctuation, whitespace runs, and the common <=3-digit chunks.
+ * Comparing complete renders catches byte wins such as `establishment.` ->
+ * `@0+` that increase real cl100k/o200k tokens despite shorter text. */
+static size_t tree_token_shape_units(const char *text) {
+    const unsigned char *p = (const unsigned char *)text;
+    size_t units = 0;
+    while (p && *p) {
+        if (isdigit(*p)) {
+            size_t digits = 0;
+            while (isdigit(*p)) {
+                digits++;
+                p++;
+            }
+            units += (digits + 2U) / 3U;
+            continue;
+        }
+        if (isalpha(*p) || *p >= 0x80U) {
+            do {
+                p++;
+            } while (*p && (isalpha(*p) || *p >= 0x80U));
+            units++;
+            continue;
+        }
+        if (isspace(*p)) {
+            do {
+                p++;
+            } while (*p && isspace(*p));
+            units++;
+            continue;
+        }
+
+        p++;
+        units++;
+    }
+    return units;
+}
+
+static bool tree_column_is_string(const bool *string_cols, int col) {
+    return !string_cols || string_cols[col];
+}
+
+static bool tree_column_is_prefixable(const bool *string_cols, const bool *prefix_cols, int col) {
+    return prefix_cols && prefix_cols[col] && tree_column_is_string(string_cols, col);
+}
+
+static void tree_render_table_direct(cbm_sb_t *sb, const char *key, int nrows,
+                                     const char *const *cols, int ncols, const char *const *cells,
+                                     const bool *string_cols) {
+    cbm_tree_table_header(sb, key, nrows, cols, ncols);
+    for (int row = 0; row < nrows; row++) {
+        cbm_tree_row_begin(sb);
+        for (int col = 0; col < ncols; col++) {
+            const char *value = cells[(size_t)row * (size_t)ncols + (size_t)col];
+            if (tree_column_is_string(string_cols, col)) {
+                cbm_tree_cell_str(sb, value, col == 0);
+            } else {
+                if (col > 0) {
+                    cbm_sb_append_n(sb, " ", 1);
+                }
+                cbm_sb_append(sb, value ? value : "null");
+            }
+        }
+        cbm_tree_row_end(sb);
+    }
+}
+
+static int tree_string_ptr_compare(const void *left, const void *right) {
+    const char *const *a = (const char *const *)left;
+    const char *const *b = (const char *const *)right;
+    return strcmp(*a, *b);
+}
+
+static int tree_prefix_score_compare(const void *left, const void *right) {
+    const tree_prefix_candidate_t *a = (const tree_prefix_candidate_t *)left;
+    const tree_prefix_candidate_t *b = (const tree_prefix_candidate_t *)right;
+    if (a->score != b->score) {
+        return a->score > b->score ? -1 : 1;
+    }
+    if (a->len != b->len) {
+        return a->len > b->len ? -1 : 1;
+    }
+    return strcmp(a->text, b->text);
+}
+
+static bool tree_prefix_candidate_add(tree_prefix_candidate_t *candidates, int *count,
+                                      const char *text, size_t len) {
+    if (len < TREE_PREFIX_MIN_LEN || len > TREE_PREFIX_MAX_LEN) {
+        return true;
+    }
+    for (int i = 0; i < *count; i++) {
+        if (candidates[i].len == len && memcmp(candidates[i].text, text, len) == 0) {
+            return true;
+        }
+    }
+    if (*count >= TREE_PREFIX_MAX_CANDIDATES) {
+        return true;
+    }
+    char *copy = (char *)malloc(len + 1);
+    if (!copy) {
+        return false;
+    }
+    memcpy(copy, text, len);
+    copy[len] = '\0';
+    candidates[*count].text = copy;
+    candidates[*count].len = len;
+    (*count)++;
+    return true;
+}
+
+static size_t tree_semantic_prefix_boundary(const char *text, size_t shared) {
+    size_t boundary = 0;
+    for (size_t i = 0; i < shared; i++) {
+        if (text[i] == '/' || text[i] == '\\' || text[i] == '.') {
+            boundary = i + 1;
+        } else if (text[i] == ':' && i + 1 < shared && text[i + 1] == ':') {
+            boundary = i + 2;
+            i++;
+        }
+    }
+    return boundary;
+}
+
+/* Values are sorted once before candidate scoring.  Binary-searching the
+ * contiguous range that shares a prefix avoids rescanning every cell for
+ * every candidate (up to 512 * 8192 comparisons in the bounded worst case). */
+static size_t tree_sorted_prefix_count(const char *const *values, size_t count,
+                                       const tree_prefix_candidate_t *candidate) {
+    size_t lo = 0;
+    size_t hi = count;
+    while (lo < hi) {
+        size_t mid = lo + (hi - lo) / 2;
+        if (strncmp(values[mid], candidate->text, candidate->len) < 0) {
+            lo = mid + 1;
+        } else {
+            hi = mid;
+        }
+    }
+    size_t first = lo;
+    hi = count;
+    while (lo < hi) {
+        size_t mid = lo + (hi - lo) / 2;
+        if (strncmp(values[mid], candidate->text, candidate->len) <= 0) {
+            lo = mid + 1;
+        } else {
+            hi = mid;
+        }
+    }
+    return lo - first;
+}
+
+static int tree_prefix_choice(const char *value, const tree_prefix_candidate_t *candidates,
+                              int selected_count, bool active_only) {
+    if (!value) {
+        return -1;
+    }
+    size_t value_len = strlen(value);
+    if (output_text_requires_encoding(value, value_len) || needs_quotes(value)) {
+        return -1;
+    }
+    int choice = -1;
+    size_t longest = 0;
+    for (int i = 0; i < selected_count; i++) {
+        if ((active_only && !candidates[i].active) || value_len < candidates[i].len ||
+            memcmp(value, candidates[i].text, candidates[i].len) != 0) {
+            continue;
+        }
+        if (candidates[i].len > longest) {
+            choice = i;
+            longest = candidates[i].len;
+        }
+    }
+    return choice;
+}
+
+/* Unquoted @N+suffix is reserved for a directory reference whenever a table
+ * has a sibling <key>_refs table. Quote matching literals so a decoder can
+ * always distinguish data from an encoded reference. */
+static bool tree_looks_like_prefix_ref(const char *value) {
+    if (!value || value[0] != '@' || !isdigit((unsigned char)value[1])) {
+        return false;
+    }
+    const char *p = value + 2;
+    while (isdigit((unsigned char)*p)) {
+        p++;
+    }
+    return *p == '+';
+}
+
+static void tree_append_unambiguous_literal(cbm_sb_t *sb, const char *value) {
+    if (tree_looks_like_prefix_ref(value)) {
+        append_quoted(sb, value);
+    } else {
+        append_value(sb, value);
+    }
+}
+
+static void tree_prefix_candidates_free(tree_prefix_candidate_t *candidates, int count) {
+    for (int i = 0; i < count; i++) {
+        free(candidates[i].text);
+    }
+}
+
+static void tree_table_rows_impl(cbm_sb_t *sb, const char *key, int nrows, const char *const *cols,
+                                 int ncols, const char *const *cells, const bool *string_cols,
+                                 const bool *prefix_cols) {
+    if (!sb || !key || !cols || !cells || nrows < TREE_PREFIX_MIN_USES || ncols < 1 ||
+        !prefix_cols || (size_t)nrows > (size_t)-1 / (size_t)ncols) {
+        if (sb && key && cols && cells && nrows >= 0 && ncols >= 0) {
+            tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        }
+        return;
+    }
+
+    size_t cell_count = (size_t)nrows * (size_t)ncols;
+    if (cell_count > TREE_PREFIX_MAX_CELLS) {
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+
+    const char **seeds = (const char **)malloc(sizeof(*seeds) * TREE_PREFIX_MAX_SEEDS);
+    tree_prefix_candidate_t *candidates =
+        (tree_prefix_candidate_t *)calloc(TREE_PREFIX_MAX_CANDIDATES, sizeof(*candidates));
+    if (!seeds || !candidates) {
+        free(seeds);
+        free(candidates);
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+
+    int seed_count = 0;
+    for (size_t i = 0; i < cell_count && seed_count < TREE_PREFIX_MAX_SEEDS; i++) {
+        int col = (int)(i % (size_t)ncols);
+        if (!tree_column_is_prefixable(string_cols, prefix_cols, col)) {
+            continue;
+        }
+        const char *value = cells[i];
+        if (value && strlen(value) >= TREE_PREFIX_MIN_LEN && !needs_quotes(value)) {
+            seeds[seed_count++] = value;
+        }
+    }
+    if (seed_count < TREE_PREFIX_MIN_USES) {
+        free(seeds);
+        free(candidates);
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+    qsort(seeds, (size_t)seed_count, sizeof(*seeds), tree_string_ptr_compare);
+
+    int candidate_count = 0;
+    bool candidate_oom = false;
+    for (int i = 1; i < seed_count && !candidate_oom; i++) {
+        const char *left = seeds[i - 1];
+        const char *right = seeds[i];
+        size_t shared = 0;
+        while (left[shared] && right[shared] && left[shared] == right[shared] &&
+               shared < TREE_PREFIX_MAX_LEN) {
+            shared++;
+        }
+        if (left[shared] == '\0' && right[shared] == '\0') {
+            candidate_oom = !tree_prefix_candidate_add(candidates, &candidate_count, left, shared);
+        }
+        size_t boundary = tree_semantic_prefix_boundary(left, shared);
+        if (!candidate_oom && boundary >= TREE_PREFIX_MIN_LEN) {
+            candidate_oom =
+                !tree_prefix_candidate_add(candidates, &candidate_count, left, boundary);
+        }
+    }
+    free(seeds);
+    if (candidate_oom || candidate_count == 0) {
+        tree_prefix_candidates_free(candidates, candidate_count);
+        free(candidates);
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+
+    const char **eligible_values = (const char **)malloc(sizeof(*eligible_values) * cell_count);
+    if (!eligible_values) {
+        tree_prefix_candidates_free(candidates, candidate_count);
+        free(candidates);
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+    size_t eligible_count = 0;
+    for (size_t cell = 0; cell < cell_count; cell++) {
+        int col = (int)(cell % (size_t)ncols);
+        const char *value = cells[cell];
+        if (tree_column_is_prefixable(string_cols, prefix_cols, col) && value &&
+            strlen(value) >= TREE_PREFIX_MIN_LEN && !needs_quotes(value) &&
+            !output_text_requires_encoding(value, strlen(value))) {
+            eligible_values[eligible_count++] = value;
+        }
+    }
+    qsort(eligible_values, eligible_count, sizeof(*eligible_values), tree_string_ptr_compare);
+
+    /* Score candidates independently first. The final byte-for-byte render
+     * comparison below accounts for overlap and directory overhead exactly. */
+    for (int i = 0; i < candidate_count; i++) {
+        candidates[i].uses =
+            tree_sorted_prefix_count(eligible_values, eligible_count, &candidates[i]);
+        if (candidates[i].uses >= TREE_PREFIX_MIN_USES && candidates[i].len > 5) {
+            size_t gross = candidates[i].uses * (candidates[i].len - 5);
+            size_t entry_cost = candidates[i].len + 12;
+            candidates[i].score = gross > entry_cost ? gross - entry_cost : 0;
+        }
+    }
+    free(eligible_values);
+    qsort(candidates, (size_t)candidate_count, sizeof(*candidates), tree_prefix_score_compare);
+
+    int selected_count = 0;
+    while (selected_count < candidate_count && selected_count < TREE_PREFIX_MAX_REFS &&
+           candidates[selected_count].score > 0) {
+        selected_count++;
+    }
+    if (selected_count == 0) {
+        tree_prefix_candidates_free(candidates, candidate_count);
+        free(candidates);
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+
+    size_t exclusive_uses[TREE_PREFIX_MAX_REFS] = {0};
+    for (size_t cell = 0; cell < cell_count; cell++) {
+        int col = (int)(cell % (size_t)ncols);
+        if (!tree_column_is_prefixable(string_cols, prefix_cols, col)) {
+            continue;
+        }
+        int choice = tree_prefix_choice(cells[cell], candidates, selected_count, false);
+        if (choice >= 0) {
+            exclusive_uses[choice]++;
+        }
+    }
+
+    int active_count = 0;
+    for (int i = 0; i < selected_count; i++) {
+        candidates[i].active = exclusive_uses[i] >= TREE_PREFIX_MIN_USES;
+        if (candidates[i].active) {
+            candidates[i].id = active_count++;
+        }
+    }
+    if (active_count == 0) {
+        tree_prefix_candidates_free(candidates, candidate_count);
+        free(candidates);
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+
+    signed char *active_choices = (signed char *)malloc(cell_count);
+    if (!active_choices) {
+        tree_prefix_candidates_free(candidates, candidate_count);
+        free(candidates);
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+    for (size_t cell = 0; cell < cell_count; cell++) {
+        int col = (int)(cell % (size_t)ncols);
+        int choice = tree_column_is_prefixable(string_cols, prefix_cols, col)
+                         ? tree_prefix_choice(cells[cell], candidates, selected_count, true)
+                         : -1;
+        active_choices[cell] = (signed char)choice;
+    }
+
+    size_t key_len = strlen(key);
+    char *refs_key = (char *)malloc(key_len + sizeof("_refs"));
+    char *rule_key = (char *)malloc(key_len + sizeof("_ref_rule"));
+    if (!refs_key || !rule_key) {
+        free(refs_key);
+        free(rule_key);
+        free(active_choices);
+        tree_prefix_candidates_free(candidates, candidate_count);
+        free(candidates);
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+        return;
+    }
+    snprintf(refs_key, key_len + sizeof("_refs"), "%s_refs", key);
+    snprintf(rule_key, key_len + sizeof("_ref_rule"), "%s_ref_rule", key);
+
+    cbm_sb_t plain;
+    cbm_sb_init(&plain);
+    tree_render_table_direct(&plain, key, nrows, cols, ncols, cells, string_cols);
+    char *plain_text = cbm_sb_finish(&plain);
+
+    cbm_sb_t compact;
+    cbm_sb_init(&compact);
+    const char *ref_cols[] = {"id", "prefix"};
+    cbm_tree_table_header(&compact, refs_key, active_count, ref_cols, 2);
+    for (int i = 0; i < selected_count; i++) {
+        if (!candidates[i].active) {
+            continue;
+        }
+        cbm_tree_row_begin(&compact);
+        cbm_tree_cell_int(&compact, candidates[i].id, true);
+        cbm_sb_append_n(&compact, " ", 1);
+        /* Directories are declarations, never recursively expanded refs. Quote
+         * a ref-looking prefix anyway so a simple decoder cannot mistake it
+         * for another directory entry. */
+        tree_append_unambiguous_literal(&compact, candidates[i].text);
+        cbm_tree_row_end(&compact);
+    }
+    cbm_tree_scalar_str(&compact, rule_key, "@N+suffix=prefix+suffix");
+    cbm_tree_table_header(&compact, key, nrows, cols, ncols);
+    for (int row = 0; row < nrows; row++) {
+        cbm_tree_row_begin(&compact);
+        for (int col = 0; col < ncols; col++) {
+            if (col > 0) {
+                cbm_sb_append_n(&compact, " ", 1);
+            }
+            const char *value = cells[(size_t)row * (size_t)ncols + (size_t)col];
+            bool string_cell = tree_column_is_string(string_cols, col);
+            int choice = active_choices[(size_t)row * (size_t)ncols + (size_t)col];
+            if (choice >= 0) {
+                char ref[24];
+                snprintf(ref, sizeof(ref), "@%d+", candidates[choice].id);
+                cbm_sb_append(&compact, ref);
+                cbm_sb_append(&compact, value + candidates[choice].len);
+            } else if (string_cell) {
+                tree_append_unambiguous_literal(&compact, value);
+            } else {
+                cbm_sb_append(&compact, value ? value : "null");
+            }
+        }
+        cbm_tree_row_end(&compact);
+    }
+    char *compact_text = cbm_sb_finish(&compact);
+
+    bool use_compact = false;
+    if (plain_text && compact_text) {
+        size_t plain_len = strlen(plain_text);
+        size_t compact_len = strlen(compact_text);
+        size_t saving = plain_len > compact_len ? plain_len - compact_len : 0;
+        size_t plain_token_shape = tree_token_shape_units(plain_text);
+        size_t compact_token_shape = tree_token_shape_units(compact_text);
+        size_t token_shape_saving =
+            plain_token_shape > compact_token_shape ? plain_token_shape - compact_token_shape : 0;
+        use_compact =
+            saving >= TREE_PREFIX_MIN_SAVING &&
+            saving * 100 >= plain_len * TREE_PREFIX_MIN_PERCENT &&
+            token_shape_saving * 100 >= plain_token_shape * TREE_PREFIX_MIN_TOKEN_SHAPE_PERCENT;
+    }
+    if (use_compact) {
+        cbm_sb_append(sb, compact_text);
+    } else if (plain_text) {
+        cbm_sb_append(sb, plain_text);
+    } else {
+        tree_render_table_direct(sb, key, nrows, cols, ncols, cells, string_cols);
+    }
+
+    free(plain_text);
+    free(compact_text);
+    free(refs_key);
+    free(rule_key);
+    free(active_choices);
+    tree_prefix_candidates_free(candidates, candidate_count);
+    free(candidates);
+}
+
+void cbm_tree_table_rows_typed(cbm_sb_t *sb, const char *key, int nrows, const char *const *cols,
+                               int ncols, const char *const *cells, const bool *string_cols) {
+    tree_table_rows_impl(sb, key, nrows, cols, ncols, cells, string_cols, NULL);
+}
+
+void cbm_tree_table_rows(cbm_sb_t *sb, const char *key, int nrows, const char *const *cols,
+                         int ncols, const char *const *cells) {
+    tree_table_rows_impl(sb, key, nrows, cols, ncols, cells, NULL, NULL);
+}
+
+void cbm_tree_table_rows_profiled(cbm_sb_t *sb, const char *key, int nrows, const char *const *cols,
+                                  int ncols, const char *const *cells, const bool *string_cols,
+                                  const bool *prefix_cols) {
+    tree_table_rows_impl(sb, key, nrows, cols, ncols, cells, string_cols, prefix_cols);
+}
+
+/* ── Generic JSON projection ────────────────────────────────────── */
+
+enum { JSON_TREE_MAX_DEPTH = 32 };
+
+static void json_tree_indent(cbm_sb_t *sb, int depth) {
+    for (int i = 0; i < depth; i++) {
+        cbm_sb_append_n(sb, "  ", 2);
+    }
+}
+
+/* Source and Markdown lose substantial model utility when every newline is
+ * escaped into one long quoted scalar. Use the familiar YAML block markers:
+ * `|-` means no trailing newline, `|` means one, and `|+` preserves several.
+ * The content remains readable/copyable and valid UTF-8. */
+static void json_tree_block_string(cbm_sb_t *sb, const char *text, size_t len, int depth) {
+    size_t trailing_newlines = 0;
+    while (trailing_newlines < len && text[len - trailing_newlines - 1] == '\n') {
+        trailing_newlines++;
+    }
+    cbm_sb_append(sb, trailing_newlines == 0 ? "|-\n" : trailing_newlines == 1 ? "|\n" : "|+\n");
+
+    size_t line_offset = 0;
+    for (;;) {
+        const char *line = text + line_offset;
+        const char *newline = memchr(line, '\n', len - line_offset);
+        const char *end = newline ? newline : text + len;
+        json_tree_indent(sb, depth + 1);
+        for (const char *p = line; p < end; p++) {
+            unsigned char c = (unsigned char)*p;
+            if (c == '\t' || (c >= 0x20 && c != 0x7f && c < 0x80)) {
+                cbm_sb_append_n(sb, p, 1);
+            } else if (c >= 0x80) {
+                size_t sequence = utf8_sequence_length((const unsigned char *)p, (size_t)(end - p));
+                if (sequence && p + sequence <= end) {
+                    cbm_sb_append_n(sb, p, sequence);
+                    p += sequence - 1;
+                } else {
+                    cbm_sb_append_n(sb, "\xEF\xBF\xBD", 3);
+                }
+            } else {
+                char escaped[8];
+                snprintf(escaped, sizeof(escaped), "\\u%04x", (unsigned)c);
+                cbm_sb_append(sb, escaped);
+            }
+        }
+        cbm_sb_append_n(sb, "\n", 1);
+        if (!newline) {
+            break;
+        }
+        line_offset = (size_t)(newline - text) + 1;
+        if (line_offset == len) {
+            break;
+        }
+    }
+}
+
+static void json_tree_scalar(cbm_sb_t *sb, yyjson_val *value) {
+    if (yyjson_is_str(value)) {
+        append_value_n(sb, yyjson_get_str(value), yyjson_get_len(value));
+    } else if (yyjson_is_bool(value)) {
+        cbm_sb_append(sb, yyjson_get_bool(value) ? "true" : "false");
+    } else if (yyjson_is_null(value)) {
+        cbm_sb_append(sb, "null");
+    } else if (yyjson_is_num(value)) {
+        char *encoded = yyjson_val_write(value, 0, NULL);
+        cbm_sb_append(sb, encoded ? encoded : "null");
+        free(encoded);
+    } else {
+        char *encoded = yyjson_val_write(value, 0, NULL);
+        append_value(sb, encoded ? encoded : "null");
+        free(encoded);
+    }
+}
+
+static bool json_tree_array_is_object_table(yyjson_val *array, yyjson_val **first_out) {
+    if (!array || !first_out) {
+        return false;
+    }
+    size_t count = yyjson_arr_size(array);
+    if (count == 0) {
+        return false;
+    }
+    yyjson_val *first = yyjson_arr_get_first(array);
+    if (!first || !yyjson_is_obj(first) || yyjson_obj_size(first) == 0) {
+        return false;
+    }
+    size_t expected = yyjson_obj_size(first);
+    size_t index;
+    size_t maximum;
+    yyjson_val *item;
+    yyjson_arr_foreach(array, index, maximum, item) {
+        if (!yyjson_is_obj(item) || yyjson_obj_size(item) != expected) {
+            return false;
+        }
+        size_t key_index;
+        size_t key_maximum;
+        yyjson_val *key;
+        yyjson_val *unused;
+        yyjson_obj_foreach(first, key_index, key_maximum, key, unused) {
+            if (!yyjson_obj_getn(item, yyjson_get_str(key), yyjson_get_len(key))) {
+                return false;
+            }
+        }
+    }
+    *first_out = first;
+    return true;
+}
+
+static void json_tree_value(cbm_sb_t *sb, const char *key_name, size_t key_len, yyjson_val *value,
+                            int depth);
+
+static void json_tree_object_table(cbm_sb_t *sb, const char *key_name, size_t key_len,
+                                   yyjson_val *array, yyjson_val *first, int depth) {
+    if (!sb || !key_name || !array || !first) {
+        return;
+    }
+    json_tree_indent(sb, depth);
+    append_key_n(sb, key_name, key_len);
+    char count[48];
+    snprintf(count, sizeof(count), ": %zu  (cols:", yyjson_arr_size(array));
+    cbm_sb_append(sb, count);
+
+    size_t key_index;
+    size_t key_maximum;
+    yyjson_val *column;
+    yyjson_val *unused;
+    yyjson_obj_foreach(first, key_index, key_maximum, column, unused) {
+        cbm_sb_append_n(sb, " ", 1);
+        append_key_n(sb, yyjson_get_str(column), yyjson_get_len(column));
+    }
+    cbm_sb_append_n(sb, ")\n", 2);
+
+    size_t row_index;
+    size_t row_maximum;
+    yyjson_val *row;
+    yyjson_arr_foreach(array, row_index, row_maximum, row) {
+        json_tree_indent(sb, depth + 1);
+        bool first_cell = true;
+        yyjson_obj_foreach(first, key_index, key_maximum, column, unused) {
+            if (!first_cell) {
+                cbm_sb_append_n(sb, " ", 1);
+            }
+            yyjson_val *cell = yyjson_obj_getn(row, yyjson_get_str(column), yyjson_get_len(column));
+            json_tree_scalar(sb, cell);
+            first_cell = false;
+        }
+        cbm_sb_append_n(sb, "\n", 1);
+    }
+}
+
+static void json_tree_array(cbm_sb_t *sb, const char *key_name, size_t key_len, yyjson_val *array,
+                            int depth) {
+    yyjson_val *first = NULL;
+    if (json_tree_array_is_object_table(array, &first)) {
+        json_tree_object_table(sb, key_name, key_len, array, first, depth);
+        return;
+    }
+
+    json_tree_indent(sb, depth);
+    append_key_n(sb, key_name, key_len);
+    char count[48];
+    snprintf(count, sizeof(count), ": %zu\n", yyjson_arr_size(array));
+    cbm_sb_append(sb, count);
+    size_t index;
+    size_t maximum;
+    yyjson_val *item;
+    yyjson_arr_foreach(array, index, maximum, item) {
+        if (yyjson_is_obj(item)) {
+            json_tree_indent(sb, depth + 1);
+            cbm_sb_append(sb, "-\n");
+            size_t field_index;
+            size_t field_maximum;
+            yyjson_val *field;
+            yyjson_val *field_value;
+            yyjson_obj_foreach(item, field_index, field_maximum, field, field_value) {
+                json_tree_value(sb, yyjson_get_str(field), yyjson_get_len(field), field_value,
+                                depth + 2);
+            }
+        } else if (yyjson_is_arr(item)) {
+            json_tree_value(sb, "-", 1, item, depth + 1);
+        } else {
+            json_tree_indent(sb, depth + 1);
+            cbm_sb_append(sb, "- ");
+            json_tree_scalar(sb, item);
+            cbm_sb_append_n(sb, "\n", 1);
+        }
+    }
+}
+
+static void json_tree_value(cbm_sb_t *sb, const char *key_name, size_t key_len, yyjson_val *value,
+                            int depth) {
+    if (depth >= JSON_TREE_MAX_DEPTH) {
+        json_tree_indent(sb, depth);
+        append_key_n(sb, key_name, key_len);
+        cbm_sb_append(sb, ": ");
+        char *encoded = yyjson_val_write(value, 0, NULL);
+        append_value(sb, encoded ? encoded : "null");
+        free(encoded);
+        cbm_sb_append_n(sb, "\n", 1);
+        return;
+    }
+    if (yyjson_is_obj(value)) {
+        json_tree_indent(sb, depth);
+        append_key_n(sb, key_name, key_len);
+        cbm_sb_append(sb, ":\n");
+        size_t index;
+        size_t maximum;
+        yyjson_val *key;
+        yyjson_val *child;
+        yyjson_obj_foreach(value, index, maximum, key, child) {
+            json_tree_value(sb, yyjson_get_str(key), yyjson_get_len(key), child, depth + 1);
+        }
+    } else if (yyjson_is_arr(value)) {
+        json_tree_array(sb, key_name, key_len, value, depth);
+    } else if (yyjson_is_str(value) &&
+               !memchr(yyjson_get_str(value), '\0', yyjson_get_len(value)) &&
+               (memchr(yyjson_get_str(value), '\n', yyjson_get_len(value)) ||
+                memchr(yyjson_get_str(value), '\r', yyjson_get_len(value)))) {
+        json_tree_indent(sb, depth);
+        append_key_n(sb, key_name, key_len);
+        cbm_sb_append(sb, ": ");
+        json_tree_block_string(sb, yyjson_get_str(value), yyjson_get_len(value), depth);
+    } else {
+        json_tree_indent(sb, depth);
+        append_key_n(sb, key_name, key_len);
+        cbm_sb_append(sb, ": ");
+        json_tree_scalar(sb, value);
+        cbm_sb_append_n(sb, "\n", 1);
+    }
+}
+
+char *cbm_json_to_tree(const char *json) {
+    if (!json) {
+        return NULL;
+    }
+    yyjson_doc *document = yyjson_read(json, strlen(json), 0);
+    if (!document) {
+        return NULL;
+    }
+    yyjson_val *root = yyjson_doc_get_root(document);
+    cbm_sb_t sb;
+    cbm_sb_init(&sb);
+    if (yyjson_is_obj(root)) {
+        size_t index;
+        size_t maximum;
+        yyjson_val *key;
+        yyjson_val *value;
+        yyjson_obj_foreach(root, index, maximum, key, value) {
+            json_tree_value(&sb, yyjson_get_str(key), yyjson_get_len(key), value, 0);
+        }
+    } else if (yyjson_is_arr(root)) {
+        json_tree_array(&sb, "items", sizeof("items") - 1, root, 0);
+    } else {
+        cbm_sb_append(&sb, "value: ");
+        json_tree_scalar(&sb, root);
+        cbm_sb_append_n(&sb, "\n", 1);
+    }
+    yyjson_doc_free(document);
+    return cbm_sb_finish(&sb);
+}
diff --git a/src/mcp/compact_out.h b/src/mcp/compact_out.h
index 7ebb404b1..677ba5884 100644
--- a/src/mcp/compact_out.h
+++ b/src/mcp/compact_out.h
@@ -1,11 +1,9 @@
-/* compact_out.h — TOON (Token-Oriented Object Notation) emission helpers.
+/* compact_out.h — compact tree emission helpers.
  *
  * Tool responses are consumed by LLM agents, where every byte is context
- * tokens. TOON encodes the same data as JSON but declares tabular fields
- * once in a header and streams rows line by line, cutting 40-60% of tokens
- * on homogeneous result sets at equal-or-better retrieval accuracy
- * (toonformat.dev/guide/benchmarks). Emitters here cover the subset we
- * emit: scalar key-value lines and flat tables with explicit [N] lengths.
+ * tokens. The tree format declares tabular fields once in a header and
+ * streams rows line by line, removing repeated-key overhead while retaining
+ * scalar key-value lines and explicit table lengths.
  *
  * Quoting: a cell/scalar is double-quoted iff it is empty, has leading or
  * trailing whitespace, contains a comma, quote, newline, or CR, or would
@@ -33,6 +31,13 @@ void cbm_sb_append(cbm_sb_t *sb, const char *s);
 char *cbm_sb_finish(cbm_sb_t *sb);
 void cbm_sb_free(cbm_sb_t *sb);
 
+/* Make an arbitrary byte string safe for both standard JSON and the compact
+ * tree without losing identity. Valid UTF-8 is left untouched (`*encoded` is
+ * NULL). Invalid input becomes `@bytes:<lowercase hex>`; valid strings that
+ * begin with the reserved `@bytes:` or `@utf8:` prefixes become
+ * `@utf8:<original>`. The caller frees a non-NULL `*encoded`. */
+bool cbm_output_encode_text(const char *data, size_t len, char **encoded, size_t *encoded_len);
+
 /* `key: value` scalar lines (top-level, no indent). */
 void cbm_tree_scalar_str(cbm_sb_t *sb, const char *key, const char *val);
 void cbm_tree_scalar_int(cbm_sb_t *sb, const char *key, long long v);
@@ -51,4 +56,28 @@ void cbm_tree_cell_real(cbm_sb_t *sb, double v, bool first);
 void cbm_tree_cell_bool(cbm_sb_t *sb, bool v, bool first);
 void cbm_tree_row_end(cbm_sb_t *sb);
 
+/* Emit a flat string table without abbreviating cell values. `cells` is
+ * row-major with nrows*ncols entries. */
+void cbm_tree_table_rows(cbm_sb_t *sb, const char *key, int nrows, const char *const *cols,
+                         int ncols, const char *const *cells);
+
+/* Mixed string/literal variant. Literal columns (numbers/booleans) retain
+ * their unquoted types. NULL string_cols means every column is a string. */
+void cbm_tree_table_rows_typed(cbm_sb_t *sb, const char *key, int nrows, const char *const *cols,
+                               int ncols, const char *const *cells, const bool *string_cols);
+
+/* Semantic prefix-directory variant. Only columns explicitly marked in
+ * prefix_cols may be factored, so labels, diagnostics, and arbitrary query
+ * strings are never rewritten. The directory activates only when the exact
+ * rendering saves at least 15% and 64 bytes and a conservative model-neutral
+ * token-shape proxy saves at least 1%. */
+void cbm_tree_table_rows_profiled(cbm_sb_t *sb, const char *key, int nrows, const char *const *cols,
+                                  int ncols, const char *const *cells, const bool *string_cols,
+                                  const bool *prefix_cols);
+
+/* Convert an arbitrary JSON value to the compact tree representation used by
+ * lean MCP responses. Homogeneous object arrays become header-once tables;
+ * nested values remain lossless JSON cells. Returns a heap string. */
+char *cbm_json_to_tree(const char *json);
+
 #endif /* CBM_MCP_COMPACT_OUT_H */
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index a0d3269f0..ea1d731e9 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -36,6 +36,11 @@ enum {
     MCP_TOOLS_PAGE_SIZE = 8,
     MCP_HELP_TOOLS_WRAP_COL = 74, /* --help tool list stays readable on 80-col terminals */
     MCP_MAX_CROSS_REPO_TARGETS = 4096,
+    MCP_QUERY_MAX_VISIBLE_ROWS = 99998,
+    /* max_output_tokens is model-neutral sizing guidance, not a tokenizer
+     * promise. The actual cross-platform contract is this deterministic UTF-8
+     * byte ceiling, applied only at whole semantic-unit boundaries. */
+    MCP_OUTPUT_BYTES_PER_TOKEN_ESTIMATE = 4,
 };
 #define MCP_MS_TO_US 1000LL
 #define MCP_S_TO_US 1000000LL
@@ -61,6 +66,7 @@ enum {
 #include "foundation/log.h"
 #include "foundation/limits.h"
 #include "foundation/subprocess.h"
+#include "foundation/sha256.h"
 #include "mcp/index_supervisor.h"
 #include "mcp/compact_out.h"
 #include "foundation/str_util.h"
@@ -81,9 +87,11 @@ enum {
 #define mcp_fdopen _fdopen
 #define mcp_close _close
 #else
+#include <fnmatch.h>
 #include <unistd.h>
 #include <poll.h>
 #include <fcntl.h>
+#include <sys/wait.h>
 #define mcp_fdopen fdopen
 #define mcp_close close
 #endif
@@ -138,13 +146,70 @@ static char *heap_strdup(const char *s) {
     return d;
 }
 
-/* Write yyjson_mut_doc to heap-allocated JSON string.
- * ALLOW_INVALID_UNICODE: some database strings may contain non-UTF-8 bytes
- * from older indexing runs — don't fail serialization over it. */
+/* Replace non-UTF-8 strings inside a mutable document before standard JSON
+ * serialization. Payload documents also escape literal reserved prefixes;
+ * final JSON-RPC envelopes preserve already-normalized payload strings so
+ * structuredContent does not acquire a second @utf8: layer. */
+static bool yy_mut_normalize_output_text(yyjson_mut_doc *doc, yyjson_mut_val *value,
+                                         bool escape_reserved) {
+    if (yyjson_mut_is_str(value)) {
+        char *encoded = NULL;
+        size_t encoded_len = 0;
+        if (!cbm_output_encode_text(yyjson_mut_get_str(value), yyjson_mut_get_len(value), &encoded,
+                                    &encoded_len)) {
+            return false;
+        }
+        if (!encoded) {
+            return true;
+        }
+        if (!escape_reserved && strncmp(encoded, "@utf8:", 6) == 0) {
+            free(encoded);
+            return true;
+        }
+        yyjson_mut_val *owned = yyjson_mut_strncpy(doc, encoded, encoded_len);
+        free(encoded);
+        return owned && yyjson_mut_set_strn(value, yyjson_mut_get_str(owned), encoded_len);
+    }
+    if (yyjson_mut_is_arr(value)) {
+        size_t index;
+        size_t maximum;
+        yyjson_mut_val *item;
+        yyjson_mut_arr_foreach(value, index, maximum, item) {
+            if (!yy_mut_normalize_output_text(doc, item, escape_reserved)) {
+                return false;
+            }
+        }
+    } else if (yyjson_mut_is_obj(value)) {
+        size_t index;
+        size_t maximum;
+        yyjson_mut_val *key;
+        yyjson_mut_val *item;
+        yyjson_mut_obj_foreach(value, index, maximum, key, item) {
+            if (!yy_mut_normalize_output_text(doc, key, escape_reserved) ||
+                !yy_mut_normalize_output_text(doc, item, escape_reserved)) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
+static char *yy_doc_write_output(yyjson_mut_doc *doc, bool escape_reserved) {
+    yyjson_mut_val *root = doc ? yyjson_mut_doc_get_root(doc) : NULL;
+    if (!root || !yy_mut_normalize_output_text(doc, root, escape_reserved)) {
+        return NULL;
+    }
+    return yyjson_mut_write(doc, 0, NULL);
+}
+
+/* Tool payloads are the first encoding boundary. */
 static char *yy_doc_to_str(yyjson_mut_doc *doc) {
-    size_t len = 0;
-    char *s = yyjson_mut_write(doc, YYJSON_WRITE_ALLOW_INVALID_UNICODE, &len);
-    return s;
+    return yy_doc_write_output(doc, true);
+}
+
+/* Payloads embedded in a JSON-RPC envelope have already crossed that boundary. */
+static char *yy_final_doc_to_str(yyjson_mut_doc *doc) {
+    return yy_doc_write_output(doc, false);
 }
 
 /* ══════════════════════════════════════════════════════════════════
@@ -247,7 +312,7 @@ char *cbm_jsonrpc_format_response(const cbm_jsonrpc_response_t *resp) {
         yyjson_mut_obj_add_null(doc, root, "result");
     }
 
-    char *out = yy_doc_to_str(doc);
+    char *out = yy_final_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
     return out;
 }
@@ -260,13 +325,23 @@ char *cbm_jsonrpc_format_error(int64_t id, int code, const char *message) {
     yyjson_mut_obj_add_str(doc, root, "jsonrpc", "2.0");
     yyjson_mut_obj_add_int(doc, root, "id", id);
 
+    char *encoded_message = NULL;
+    size_t encoded_message_len = 0;
+    const char *raw_message = message ? message : "";
+    if (!cbm_output_encode_text(raw_message, strlen(raw_message), &encoded_message,
+                                &encoded_message_len)) {
+        yyjson_mut_doc_free(doc);
+        return NULL;
+    }
+
     yyjson_mut_val *err = yyjson_mut_obj(doc);
     yyjson_mut_obj_add_int(doc, err, "code", code);
-    yyjson_mut_obj_add_str(doc, err, "message", message);
+    yyjson_mut_obj_add_str(doc, err, "message", encoded_message ? encoded_message : raw_message);
     yyjson_mut_obj_add_val(doc, root, "error", err);
 
-    char *out = yy_doc_to_str(doc);
+    char *out = yy_final_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
+    free(encoded_message);
     return out;
 }
 
@@ -275,6 +350,19 @@ char *cbm_jsonrpc_format_error(int64_t id, int code, const char *message) {
  * ══════════════════════════════════════════════════════════════════ */
 
 char *cbm_mcp_text_result(const char *text, bool is_error) {
+    yyjson_doc *structured_doc = text ? yyjson_read(text, strlen(text), 0) : NULL;
+    yyjson_val *structured_root = structured_doc ? yyjson_doc_get_root(structured_doc) : NULL;
+    bool structured_object = structured_root && yyjson_is_obj(structured_root);
+    char *encoded_text = NULL;
+    size_t encoded_text_len = 0;
+    const char *raw_text = text ? text : "";
+    if (!structured_object &&
+        !cbm_output_encode_text(raw_text, strlen(raw_text), &encoded_text, &encoded_text_len)) {
+        yyjson_doc_free(structured_doc);
+        return NULL;
+    }
+    const char *wire_text = encoded_text ? encoded_text : raw_text;
+
     yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
     yyjson_mut_val *root = yyjson_mut_obj(doc);
     yyjson_mut_doc_set_root(doc, root);
@@ -282,23 +370,16 @@ char *cbm_mcp_text_result(const char *text, bool is_error) {
     yyjson_mut_val *content = yyjson_mut_arr(doc);
     yyjson_mut_val *item = yyjson_mut_obj(doc);
     yyjson_mut_obj_add_str(doc, item, "type", "text");
-    yyjson_mut_obj_add_str(doc, item, "text", text ? text : "");
+    yyjson_mut_obj_add_str(doc, item, "text", wire_text);
     yyjson_mut_arr_add_val(content, item);
     yyjson_mut_obj_add_val(doc, root, "content", content);
 
     bool has_structured_content = false;
-    if (text) {
-        yyjson_doc *structured_doc = yyjson_read(text, strlen(text), 0);
-        if (structured_doc) {
-            yyjson_val *structured_root = yyjson_doc_get_root(structured_doc);
-            if (yyjson_is_obj(structured_root)) {
-                yyjson_mut_val *structured = yyjson_val_mut_copy(doc, structured_root);
-                if (structured) {
-                    yyjson_mut_obj_add_val(doc, root, "structuredContent", structured);
-                    has_structured_content = true;
-                }
-            }
-            yyjson_doc_free(structured_doc);
+    if (structured_object) {
+        yyjson_mut_val *structured = yyjson_val_mut_copy(doc, structured_root);
+        if (structured) {
+            yyjson_mut_obj_add_val(doc, root, "structuredContent", structured);
+            has_structured_content = true;
         }
     }
     if (!has_structured_content && is_error) {
@@ -326,13 +407,15 @@ char *cbm_mcp_text_result(const char *text, bool is_error) {
          * tests/test_mcp.c binds all three branches; scripts/smoke-test.sh
          * asserts the same contract on the shipped binary. */
         yyjson_mut_val *structured = yyjson_mut_obj(doc);
-        yyjson_mut_obj_add_str(doc, structured, "error", text ? text : "");
+        yyjson_mut_obj_add_str(doc, structured, "error", wire_text);
         yyjson_mut_obj_add_val(doc, root, "structuredContent", structured);
     }
     yyjson_mut_obj_add_bool(doc, root, "isError", is_error);
 
-    char *out = yy_doc_to_str(doc);
+    char *out = yy_final_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
+    yyjson_doc_free(structured_doc);
+    free(encoded_text);
     return out;
 }
 
@@ -367,324 +450,255 @@ bool cbm_mcp_cancel_request_matches(const char *params_json, int64_t active_id,
 
 typedef struct {
     const char *name;
-    const char *title;
     const char *description;
     const char *input_schema; /* JSON string */
 } tool_def_t;
 
 static const tool_def_t TOOLS[] = {
-    {"index_repository", "Index repository",
-     "Index a repository into the knowledge graph. "
-     "Special mode 'cross-repo-intelligence': skip extraction, only match Routes/Channels "
-     "across projects to create CROSS_HTTP_CALLS/CROSS_ASYNC_CALLS/CROSS_CHANNEL edges. "
-     "Requires target_projects param. Ensure target projects have fresh indexes first. "
-     "COVERAGE: the response reports files that were NOT fully indexed — 'skipped' (not "
-     "indexed at all: oversized/read/parse failures) and 'parse_partial' (indexed, but "
-     "constructs inside the listed line ranges could not be parsed and MAY be missing from "
-     "the graph). The embedded lists carry counts plus a FEW EXAMPLES only; the complete "
-     "lists are in the per-run 'logfile' (path in the response) and queryable any time via "
-     "index_status or structurally via query_graph(graph=\"missed\"). Both signals are "
-     "best-effort: absence of a flag is NOT a completeness guarantee; prefer grep inside "
-     "flagged ranges. Separately, 'excluded' + 'not_indexed_files' list what was "
-     "deliberately NOT indexed (gitignore/.cbmignore/skip-lists) — by design, not failures.",
+    {"index_repository",
+     "Index a repository. full/moderate add semantics; fast omits them; cross-repo-intelligence "
+     "links services. Reports coverage gaps.",
      "{\"type\":\"object\",\"properties\":{\"repo_path\":{\"type\":\"string\",\"description\":"
-     "\"Path to the repository\"},"
+     "\"Repository path\"},"
      "\"mode\":{\"type\":\"string\","
      "\"enum\":[\"full\",\"moderate\",\"fast\",\"cross-repo-intelligence\"],"
-     "\"default\":\"full\",\"description\":\"All modes run type-aware LSP call/usage "
-     "resolution (per-file + cross-file). full: all files + similarity/semantic edges. "
-     "moderate: filtered files + similarity/semantic. fast: filtered files, no "
-     "similarity/semantic. cross-repo-intelligence: match Routes/Channels across projects.\"},"
+     "\"default\":\"full\",\"description\":\"full: all+semantic; moderate: "
+     "filtered+semantic; fast: filtered only; cross-repo-intelligence: link services.\"},"
      "\"target_projects\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},"
-     "\"description\":\"Projects to search for cross-repo links (cross-repo-intelligence mode). "
-     "Use [\\\"*\\\"] for all indexed projects. Run list_projects to see available projects.\"},"
+     "\"description\":\"Cross-repo targets; [\\\"*\\\"] means all.\"},"
      "\"name\":{\"type\":\"string\",\"description\":"
-     "\"Override the derived project name. Non-ASCII bytes are encoded and unsafe path characters "
-     "are normalized.\"},"
+     "\"Name override; Non-ASCII bytes are encoded; unsafe characters normalized.\"},"
      "\"persistence\":{\"type\":\"boolean\",\"default\":false,\"description\":"
-     "\"Write compressed artifact to .codebase-memory/graph.db.zst for team sharing. "
-     "Teammates can bootstrap from the artifact instead of full re-indexing.\"}"
+     "\"Write .codebase-memory/graph.db.zst.\"}"
      "},\"required\":[\"repo_path\"]}"},
 
-    {"search_graph", "Search graph",
-     "Search the code knowledge graph for functions, classes, routes, and variables. Use INSTEAD "
-     "OF grep/glob when finding code definitions, implementations, or relationships. Three search "
-     "modes: (1) query='update settings' for BM25 ranked full-text search with camelCase "
-     "splitting and structural label boosting — recommended for natural-language discovery; "
-     "(2) name_pattern='.*regex.*' for exact pattern matching; (3) semantic_query=[...] for "
-     "vector cosine search that bridges vocabulary (finds 'publish' when you search 'send'). "
-     "The three modes are independent and can be combined in a single call. "
-     "RESPONSE: prefix-grouped tree rows by default — a shared (qn-prefix, file) group "
-     "header printed once, then `name label lines in out` per row (full qn = group prefix "
-     "+ dot + name). in/out = selected degree across CALLS, USAGE, CALL_REFERENCE, "
-     "INHERITS, and IMPLEMENTS; other edge types are excluded. These are NOT caller/callee "
-     "counts — use trace_path for callers. Add per-node "
-     "property columns via "
-     "fields (e.g. [\"complexity\",\"signature\",\"docstring\"]); format=\"json\" returns "
-     "the SAME tree model as structured JSON. "
-     "PAGINATION: results are capped at limit (default 50). The response always includes "
-     "'total' (full match count before limit) and 'has_more' (true when total > "
-     "offset+returned). Detect truncation with has_more, then page by re-calling with "
-     "offset=offset+limit until has_more is false. Narrow first via label/file_pattern/"
-     "min_degree before paginating large result sets.",
+    {"search_graph",
+     "Find symbols via BM25 query, regex name/qn filters, or semantic_query. Rows keep "
+     "qn/file/lines and in/out over CALLS/USAGE/CALL_REFERENCE/INHERITS/IMPLEMENTS.",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},"
-     "\"query\":{\"type\":\"string\",\"description\":\"Natural-language or keyword full-text "
-     "search using BM25 ranking. Tokens are split on whitespace; camelCase identifiers are "
-     "indexed as individual words (updateCloudClient → update, cloud, client). Results are "
-     "ranked with structural boosting: Functions/Methods +10, Routes +8, Classes/Interfaces +5. "
-     "Noise labels (File/Folder/Module/Variable) are filtered out. When provided, name_pattern "
-     "is ignored.\"},"
+     "\"query\":{\"type\":\"string\"},"
      "\"label\":{\"type\":\"string\"},\"name_pattern\":{\"type\":\"string\"},\"qn_pattern\":{"
      "\"type\":\"string\"},\"file_pattern\":{\"type\":\"string\"},"
      "\"relationship\":{\"type\":\"string\"},\"min_degree\":{\"type\":\"integer\"},"
      "\"max_degree\":{\"type\":\"integer\"},\"exclude_entry_points\":{\"type\":\"boolean\"},"
      "\"include_connected\":{\"type\":\"boolean\"},\"semantic_query\":{"
-     "\"type\":\"array\",\"items\":{\"type\":\"string\"},\"description\":\"MUST be an ARRAY of "
-     "keyword strings (e.g. [\\\"send\\\",\\\"pubsub\\\",\\\"publish\\\"]) — NOT a single string. "
-     "Each keyword is scored independently via per-keyword min-cosine; results reflect functions "
-     "that score well on ALL keywords. Requires moderate/full index mode. Results appear in the "
-     "'semantic_results' field (separate from 'results').\"},\"limit\":{\"type\":"
-     "\"integer\",\"description\":\"Max results per call. Default 50. Response carries "
-     "'total' (full match count) and 'has_more' (true if truncated) so callers can "
-     "detect the limit and paginate.\"},\"offset\":{\"type\":\"integer\",\"default\":0,"
-     "\"description\":\"Skip the first N matching nodes. Combine with 'limit' to page: "
-     "increment offset by limit and re-call while has_more is true.\"},"
-     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\","
-     "\"description\":\"Response encoding. tree (default): prefix-grouped text rows. "
-     "json: the SAME tree model as structured JSON (groups + column-ordered row arrays).\"},"
-     "\"fields\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"description\":"
-     "\"Extra per-node property columns, e.g. complexity, cognitive, "
-     "signature, docstring, return_type, is_test, lines(int). Core row columns "
-     "(qn/label/file/lines/in/out) are always present — do not request them here. "
-     "Missing values emit as empty cells.\"},"
-     "\"detail\":{\"type\":\"string\",\"enum\":[\"ids\",\"default\"],\"default\":\"default\","
-     "\"description\":\"ids: bare qualified-name enumeration (one column) — cheapest form "
-     "for wide sweeps where per-row metadata is noise. default: full rows.\"}},"
+     "\"type\":\"array\",\"items\":{\"type\":\"string\"},\"description\":\"Not with query.\"},"
+     "\"semantic_limit\":{\"type\":\"integer\",\"default\":50,\"minimum\":0,"
+     "\"maximum\":500},"
+     "\"semantic_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0,"
+     "\"maximum\":99998},"
+     "\"limit\":{\"type\":"
+     "\"integer\",\"default\":50,\"minimum\":1,\"maximum\":500},"
+     "\"offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"default\":3200,\"minimum\":128,"
+     "\"maximum\":1000000},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"},"
+     "\"fields\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},"
+     "\"detail\":{\"type\":\"string\",\"enum\":[\"ids\",\"default\"],\"default\":\"default\"}},"
      "\"required\":[\"project\"]}"},
 
-    {"query_graph", "Query graph",
-     "Execute a Cypher query against the knowledge graph for complex multi-hop patterns, "
-     "aggregations, and cross-service analysis. The response includes 'total' (returned "
-     "row count). There is a hard 100k row ceiling — for broad queries add LIMIT in the "
-     "Cypher itself or use search_graph + offset/limit pagination instead. "
-     "COMPLEXITY / BOTTLENECKS: every Function and Method node carries queryable complexity "
-     "properties — cyclomatic (complexity), cognitive, loop_count, loop_depth (max nested-loop "
-     "depth, a polynomial-degree proxy), plus interprocedural transitive_loop_depth (worst-case "
-     "nested-loop degree propagated along CALLS edges) and a recursive flag. Additional "
-     "hot-path signals: linear_scan_in_loop (count of find/contains/indexOf-style scans inside a "
-     "loop — the hidden O(n^2) that loop_depth misses), alloc_in_loop (allocations/appends inside "
-     "a loop), recursion_in_loop (a self-call inside a loop), unguarded_recursion (recursion with "
-     "no conditionally-guarded base case), param_count and max_access_depth (structure smells). "
-     "Find all hot-path candidates in one query, e.g. MATCH (f:Function) WHERE "
-     "f.transitive_loop_depth >= 3 OR f.linear_scan_in_loop >= 1 RETURN f.qualified_name, "
-     "f.transitive_loop_depth, f.linear_scan_in_loop ORDER BY f.transitive_loop_depth DESC. "
-     "MISSED GRAPH: pass graph=\"missed\" to query the best-effort miss graph instead — the "
-     "file structure of ONLY the files the indexer could NOT fully index (Project → Folder → "
-     "File nodes with CONTAINS_FOLDER/CONTAINS_FILE edges; each File carries kind "
-     "(\"parse_partial\" = indexed but constructs in the flagged line ranges MAY be missing; "
-     "or a skip phase) and detail (the line ranges / reason)). Example: MATCH (f:File) WHERE "
-     "f.kind = \\\"parse_partial\\\" RETURN f.file_path, f.detail. Absence from this graph is "
-     "NOT a completeness guarantee.",
+    {"query_graph",
+     "Read-only Cypher for multi-hop, aggregation, complexity, or cross-service analysis. "
+     "Default: 200 visible rows with "
+     "exact/lower-bound totals and truncation; continue safely with next_cursor. "
+     "graph=missed is a file tree of flagged coverage gaps; absence is not proof of completeness. "
+     "Use get_graph_schema(diagnostics=full) for properties.",
      "{\"type\":\"object\",\"properties\":{\"query\":{\"type\":\"string\",\"description\":\"Cypher "
      "query\"},\"project\":{\"type\":\"string\"},"
      "\"graph\":{\"type\":\"string\",\"enum\":[\"code\",\"missed\"],\"default\":\"code\","
-     "\"description\":\"Which graph to query: the code knowledge graph (default) or the "
-     "missed graph (only files not fully indexed, laid out as their file structure).\"},"
+     "\"description\":\"code graph (default) or missed coverage-gap file tree.\"},"
      "\"max_rows\":{\"type\":\"integer\","
      "\"description\":"
-     "\"Optional row limit. Default: unlimited up to a 100k row "
-     "ceiling. No offset support — use search_graph for paginated browsing.\"}},"
+     "\"Visible rows (default 200; max 99998); 0 uses the legacy maximum. Evaluation is "
+     "unchanged.\",\"minimum\":0,\"default\":200},"
+     "\"offset\":{\"type\":\"integer\",\"minimum\":0,\"default\":0,"
+     "\"description\":\"Live compatibility paging; cannot be combined with cursor.\"},"
+     "\"cursor\":{\"type\":\"string\",\"description\":\"Snapshot continuation; keep "
+     "query/project/graph. Format, budget, and max_rows may change.\"},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"minimum\":128,\"maximum\":1000000,"
+     "\"description\":\"Sizing hint; hard ceiling is 4 UTF-8 bytes/token. Rows stay whole.\"},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\","
+     "\"description\":\"tree may use local @N+suffix prefix refs; json uses direct strings.\"}},"
      "\"required\":[\"query\",\"project\"]}"},
 
-    {"trace_path", "Trace path",
-     "Trace paths through the code graph. Modes: calls (callers/callees), data_flow (value "
-     "propagation with args at each hop), cross_service (through HTTP/async Route nodes). "
-     "Use INSTEAD OF grep for callers, dependencies, impact analysis, or data flow tracing. "
-     "RESPONSE: prefix-grouped tree rows — callees/callers grouped under their shared "
-     "qn-prefix, `name hop` per row (full qn = group prefix + dot + name); exact "
-     "callees_total/callers_total on every page = ALL nodes reachable within depth (transitive, "
-     "not just direct; test files excluded unless include_tests). risk/args flags use a flat "
-     "table. "
-     "`truncated: true` + `next` = more rows — pass next back as cursor. "
-     "format=\"json\" returns the SAME tree model as structured JSON.",
+    {"trace_path",
+     "Trace callers/callees, data flow, or cross-service paths. Defaults exclude tests and "
+     "resolver evidence. Rows keep qn/hop with explicit totals, relations, and continuations.",
      "{\"type\":\"object\",\"properties\":{\"function_name\":{\"type\":\"string\"},\"project\":{"
      "\"type\":\"string\"},\"direction\":{\"type\":\"string\",\"enum\":[\"inbound\",\"outbound\","
-     "\"both\"],\"default\":\"both\"},\"depth\":{\"type\":\"integer\",\"default\":3},"
+     "\"both\"],\"default\":\"both\"},\"depth\":{\"type\":\"integer\",\"default\":3,"
+     "\"minimum\":1,\"maximum\":15},"
      "\"limit\":{\"type\":\"integer\",\"default\":100,\"minimum\":1,\"maximum\":5000,"
-     "\"description\":\"Rows per page. callees_total/callers_total always carry the exact full "
-     "counts; when a page is truncated the response carries next — see cursor.\"},"
-     "\"cursor\":{\"type\":\"string\",\"description\":\"Resume token from a previous response's "
-     "'next' field. Pass it back with ALL other arguments identical to get the following page "
-     "with no duplicates. Cursors outlive nothing: after a reindex you get a stale_cursor error "
-     "— just re-run the original query.\"},\"mode\":{"
+     "\"description\":\"Rows/page; gte flags the 5000-node engine ceiling.\"},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"default\":3200,\"minimum\":128,"
+     "\"maximum\":1000000,\"description\":\"Sizing hint; hard ceiling is 4 UTF-8 bytes/token. "
+     "Evidence/args yield before nearest graph rows.\"},"
+     "\"cursor\":{\"type\":\"string\",\"description\":\"Pass next/next_cursor with traversal "
+     "args unchanged; budget may increase.\"},"
+     "\"mode\":{"
      "\"type\":\"string\",\"enum\":[\"calls\",\"data_flow\",\"cross_service\"],\"default\":"
-     "\"calls\",\"description\":\"calls: follow CALLS edges. data_flow: follow CALLS+DATA_FLOWS "
-     "with arg expressions. cross_service: follow HTTP_CALLS+ASYNC_CALLS+DATA_FLOWS through "
-     "Routes, plus CROSS_* cross-repo edges (CROSS_HTTP_CALLS/ASYNC_CALLS/CHANNEL/GRPC_CALLS/"
-     "GRAPHQL_CALLS/TRPC_CALLS) to hop into other services.\"},\"parameter_name\":{\"type\":"
-     "\"string\",\"description\":\"For data_flow mode: "
-     "scope trace to a specific parameter name\"},\"edge_types\":{\"type\":\"array\",\"items\":{"
+     "\"calls\",\"description\":\"calls, argument-aware data_flow, or service edges.\"},"
+     "\"parameter_name\":{\"type\":\"string\",\"description\":\"data_flow parameter filter.\"},"
+     "\"edge_types\":{\"type\":\"array\",\"items\":{"
      "\"type\":\"string\"}},\"risk_labels\":{\"type\":\"boolean\",\"default\":false,"
-     "\"description\":\"Add risk classification (CRITICAL/HIGH/MEDIUM/LOW) based on hop distance"
-     "\"},\"include_tests\":{\"type\":\"boolean\",\"default\":false,"
-     "\"description\":\"Include test files in results. When false (default), test files are "
-     "filtered out. When true, test nodes are included with a test column/marker.\"},"
+     "\"description\":\"Add hop-risk labels.\"},\"include_tests\":{\"type\":\"boolean\","
+     "\"default\":false},"
      "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\","
-     "\"description\":\"Response encoding. tree (default): prefix-grouped text rows. "
-     "json: the SAME tree model as structured JSON (groups + column-ordered row arrays).\"},"
+     "\"description\":\"tree chooses smaller complete direct/grouped output; json uses stable "
+     "grouped tables.\"},"
      "\"include_evidence\":{\"type\":\"boolean\",\"default\":false,"
-     "\"description\":\"Add how each hop was resolved: a strategy class (lsp | language_rule | "
-     "heuristic | unresolved) and the resolver's confidence. Off by default — it adds two "
-     "columns per row. Use it to judge whether an edge is trustworthy, not to find edges.\"}},"
+     "\"description\":\"Add resolver class and confidence.\"}},"
      "\"required\":[\"function_name\",\"project\"]}"},
 
-    {"get_code_snippet", "Get code snippet",
-     "Read source code for a function/class/symbol. IMPORTANT: First call search_graph to find the "
-     "exact qualified_name, then pass it here. This is a read tool, not a search tool. Accepts "
-     "full qualified_name (exact match) or short function name (returns suggestions if ambiguous). "
-     "If the response carries a 'coverage_note', the file was only partially indexed — constructs "
-     "in the noted line ranges may be missing from the graph (best-effort signal); prefer grep "
-     "there and treat the returned source as ground truth.",
+    {"get_code_snippet",
+     "Read a search_graph symbol. auto bounds source and outlines large containers; full "
+     "restores up to 500 lines. Source/outline pages continue; coverage_note marks gaps.",
      "{\"type\":\"object\",\"properties\":{\"qualified_name\":{\"type\":\"string\",\"description\":"
-     "\"Full qualified_name from search_graph, or short function name\"},\"project\":{"
+     "\"search_graph qn, or short name.\"},\"project\":{"
      "\"type\":\"string\"},\"include_neighbors\":{"
-     "\"type\":\"boolean\",\"default\":false}},\"required\":[\"qualified_name\",\"project\"]}"},
+     "\"type\":\"boolean\",\"default\":false},"
+     "\"source_mode\":{\"type\":\"string\",\"enum\":[\"auto\",\"full\",\"outline\"],"
+     "\"default\":\"auto\",\"description\":\"auto outlines 200+ line containers; full returns "
+     "source; "
+     "outline lists members.\"},"
+     "\"member_limit\":{\"type\":\"integer\",\"default\":50,\"minimum\":1,\"maximum\":500},"
+     "\"member_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"start_line\":{\"type\":\"integer\",\"minimum\":1},"
+     "\"max_lines\":{\"type\":\"integer\",\"minimum\":1,\"maximum\":500},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"minimum\":128,"
+     "\"maximum\":1000000,\"description\":\"auto/outline sizing hint (default 2500), hard "
+     "ceiling 4 UTF-8 bytes/token. Lines stay whole; explicit full is uncapped unless set.\"},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
+     "\"required\":[\"qualified_name\",\"project\"]}"},
 
-    {"get_graph_schema", "Get graph schema",
-     "Get the schema of the knowledge graph (node labels, edge types)",
-     "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"}},\"required\":["
+    {"get_graph_schema",
+     "Get node-label and edge-type counts. diagnostics=full also lists queryable properties.",
+     "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"},"
+     "\"diagnostics\":{\"type\":\"string\",\"enum\":[\"none\",\"full\"],\"default\":\"none\"},"
+     "\"limit\":{\"type\":\"integer\",\"default\":50,\"minimum\":1,\"maximum\":500},"
+     "\"offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0}},\"required\":["
      "\"project\"]}"},
 
-    {"get_architecture", "Get architecture",
-     "Get high-level architecture overview. DEFAULT (no aspects) is a compact summary — "
-     "overview counts, languages, packages, entry_points; request more via aspects:[...] "
-     "(structure, dependencies, routes, hotspots, boundaries, layers, clusters, file_tree) or "
-     "[\"all\"]. 'clusters' runs Leiden community detection over the call/import graph, "
-     "surfacing the de-facto modules (label, member count, cohesion score, representative "
-     "top_nodes, binding packages/edge_types) — the real architectural seams, which often cut "
-     "across the folder layout. Optional path scopes analysis to nodes under that directory "
-     "prefix (file_path).",
+    {"get_architecture",
+     "Compact counts, languages, packages, entry points. Request structure, dependencies, "
+     "routes, hotspots, boundaries, layers, clusters, cycles, or file_tree; path scopes a "
+     "directory.",
      /* The aspects enum mirrors VALID_ASPECTS (see aspect_is_valid) — update both together. */
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},\"path\":{\"type\":"
-     "\"string\",\"description\":\"Optional directory prefix to scope architecture (e.g. "
-     "apps/hoa)\"},"
+     "\"string\",\"description\":\"Directory prefix (for example apps/hoa).\"},"
      "\"aspects\":{\"type\":\"array\",\"items\":{\"type\":\"string\",\"enum\":[\"all\","
      "\"overview\",\"structure\",\"dependencies\",\"routes\",\"languages\",\"packages\","
      "\"entry_points\",\"hotspots\",\"boundaries\",\"layers\",\"file_tree\",\"clusters\","
      "\"cycles\"]},"
-     "\"description\":\"Aspects to include. 'all' = everything; 'overview' = compact summary "
-     "(all except file_tree); omit = all. 'cycles' is opt-in ONLY (never via all/overview): it "
-     "scans the whole call graph for circular CALLS dependencies (SCCs of size > 1).\"}},"
+     "\"description\":\"all=everything; overview=compact except file_tree; omitted=languages/"
+     "packages/entry_points; cycles is opt-in.\"},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
      "\"required\":[\"project\"]}"},
 
-    {"search_code", "Search code",
-     "Graph-augmented code search. Finds text patterns via grep, then enriches results with "
-     "the knowledge graph: deduplicates matches into containing functions, ranks by structural "
-     "importance (definitions first, popular functions next, tests last). "
-     "Modes: compact (default, signatures only — token efficient), full (source capped at a "
-     "60-line window around the first match per hit; source_truncated marks the cut — use "
-     "get_code_snippet for the complete symbol), "
-     "files (just file paths). Use path_filter regex to scope results. "
-     "TRUNCATION: enriched results are capped at limit (default 10). Response carries "
-     "'total_grep_matches' (raw grep hit count) and 'total_results' (deduplicated function "
-     "count) — compare to limit to detect truncation. There is no offset parameter; to see "
-     "more, raise limit or narrow the query with file_pattern / path_filter.",
+    {"search_code",
+     "Graph-ranked text search: compact symbols, full bounded source, or file paths.",
      "{\"type\":\"object\",\"properties\":{\"pattern\":{\"type\":\"string\"},\"project\":{\"type\":"
-     "\"string\"},\"file_pattern\":{\"type\":\"string\",\"description\":\"Glob for grep "
-     "--include (e.g. *.go)\"},\"path_filter\":{\"type\":\"string\",\"description\":\"Regex "
-     "filter on result file paths (e.g. ^src/ or \\\\.(go|ts)$)\"},\"mode\":{\"type\":\"string\","
-     "\"enum\":[\"compact\",\"full\",\"files\"],\"default\":\"compact\",\"description\":\"compact: "
-     "signatures+metadata (default). full: with source. files: just file list.\"},"
-     "\"context\":{\"type\":\"integer\",\"description\":\"Lines of context around each match "
-     "(like grep -C). Only used in compact mode.\"},"
+     "\"string\"},\"file_pattern\":{\"type\":\"string\"},\"path_filter\":{\"type\":\"string\"},"
+     "\"mode\":{\"type\":\"string\","
+     "\"enum\":[\"compact\",\"full\",\"files\"],\"default\":\"compact\"},"
+     "\"context\":{\"type\":\"integer\"},"
      "\"regex\":{\"type\":\"boolean\",\"default\":false},\"limit\":{\"type\":\"integer\","
-     "\"description\":\"Max enriched results per call. Default 10. Response includes "
-     "'total_grep_matches' and 'total_results' so callers can detect truncation. No "
-     "offset parameter — raise limit or narrow with file_pattern / path_filter to see more."
-     "\",\"default\":10,\"minimum\":1}},\"required\":[\"pattern\",\"project\"]}"},
-
-    {"list_projects", "List projects", "List all indexed projects",
-     "{\"type\":\"object\",\"properties\":{}}"},
-    {"delete_project", "Delete project", "Delete a project from the index",
+     "\"default\":10,\"minimum\":1,\"maximum\":500},"
+     "\"result_limit\":{\"type\":\"integer\",\"default\":10,\"minimum\":1,\"maximum\":500},"
+     "\"result_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"raw_limit\":{\"type\":\"integer\",\"default\":5,\"minimum\":0,\"maximum\":100},"
+     "\"raw_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"raw_content_offset\":{\"type\":\"integer\",\"minimum\":0,"
+     "\"description\":\"Raw-line byte offset; omit for match-centered preview.\"},"
+     "\"directory_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":0,"
+     "\"maximum\":64},"
+     "\"directory_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"match_limit\":{\"type\":\"integer\",\"default\":8,\"minimum\":1,"
+     "\"maximum\":500},"
+     "\"source_max_lines\":{\"type\":\"integer\",\"default\":20,\"minimum\":1,"
+     "\"maximum\":200},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"minimum\":128,\"maximum\":1000000},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
+     "\"required\":[\"pattern\",\"project\"]}"},
+
+    {"list_projects", "List projects with stable paging. Identity is lean; stats adds graph sizes.",
+     "{\"type\":\"object\",\"properties\":{"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"},"
+     "\"detail\":{\"type\":\"string\",\"enum\":[\"identity\",\"stats\"],"
+     "\"default\":\"identity\",\"description\":\"stats adds node/edge/database-size counts.\"},"
+     "\"limit\":{\"type\":\"integer\",\"default\":50,\"minimum\":1,\"maximum\":500},"
+     "\"offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"metadata_only\":{\"type\":\"boolean\",\"default\":false,"
+     "\"description\":\"Compatibility: omit counts, size, and branch.\"}}}"},
+    {"delete_project", "Delete a project from the index",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"}},\"required\":["
      "\"project\"]}"},
 
-    {"index_status", "Index status",
-     "Get the indexing status of a project: node/edge counts, root path, git context, and the "
-     "indexing-COVERAGE report — which files the indexer could NOT fully cover (best-effort "
-     "signal): 'parse_partial' files WERE indexed but contain line ranges tree-sitter could not "
-     "parse — constructs there MAY be missing from the graph (some are still recovered); "
-     "'skipped' files were not indexed at all (oversized/read/parse failure). Use this before "
-     "trusting graph completeness on a file: if a file is listed, ALSO grep it (especially the "
-     "flagged ranges). IMPORTANT: absence from these lists is NOT a completeness guarantee — the "
-     "signal only marks what the indexer can detect. For structural queries over the misses use "
-     "query_graph(graph=\"missed\"). The report also carries 'not_indexed' — files/dirs excluded "
-     "BY DESIGN (gitignore/.cbmignore/skip-lists): deliberate and deterministic, not failures; "
-     "change the ignore rules and re-index to include them.",
+    {"index_status",
+     "Project readiness, counts, root, and coverage gaps. diagnostics adds coverage rows; verbose "
+     "adds Git paths. Best-effort only; verify cited paths with check_index_coverage.",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},"
-     "\"verbose\":{\"type\":\"boolean\",\"default\":false,\"description\":\"Include the git "
-     "context block (worktree/shadow path variants). Only needed when debugging where an index "
-     "lives — omitted by default to keep the status lean.\"}},\"required\":["
+     "\"verbose\":{\"type\":\"boolean\",\"default\":false,\"description\":\"Add worktree/"
+     "shadow Git paths for index-location debugging.\"},"
+     "\"diagnostics\":{\"type\":\"string\",\"enum\":[\"none\",\"summary\",\"full\"],"
+     "\"default\":\"none\",\"description\":\"Coverage rows: counts, five samples, or up to "
+     "500.\"},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
+     "\"required\":["
      "\"project\"]}"},
 
-    {"check_index_coverage", "Check index coverage",
-     "Check authoritative indexing-coverage metadata for exact repository-relative paths and "
-     "bounded path scopes. Use this after graph discovery for every cited or operated-on file; "
-     "use scopes before negative/exhaustive claims because fully skipped files cannot appear in "
-     "normal graph results. Returns coverage status separately from filesystem metadata freshness, "
-     "plus structured parse-error ranges and direct-source fallback actions. The signal is "
-     "best-effort: indexed_no_recorded_gap is not a completeness guarantee. At least one of "
-     "'paths' or 'scopes' is required; the call is rejected at runtime if both are omitted.",
+    {"check_index_coverage",
+     "Best-effort exact-path/scope coverage and freshness, paged separately. full diagnostics "
+     "adds raw detail. Clean is not proof of completeness.",
      "{\"type\":\"object\",\"properties\":{"
      "\"project\":{\"type\":\"string\"},"
-     "\"paths\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"maxItems\":128,"
-     "\"description\":\"Repository-relative files to check exactly. Required if 'scopes' is "
-     "omitted.\"},"
-     "\"scopes\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"maxItems\":32,"
-     "\"description\":\"Repository-relative path prefixes; use . for the project root. Required "
-     "if 'paths' is omitted.\"},"
-     "\"scope_limit\":{\"type\":\"integer\",\"default\":200,\"minimum\":1,\"maximum\":1000},"
-     "\"scope_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0}},"
+     "\"paths\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"maxItems\":128},"
+     "\"path_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":1,\"maximum\":128},"
+     "\"path_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"scopes\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"maxItems\":32},"
+     "\"scope_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":1,\"maximum\":1000},"
+     "\"scope_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"diagnostics\":{\"type\":\"string\",\"enum\":[\"none\",\"full\"],\"default\":\"none\"},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
      "\"required\":[\"project\"]"
      "}"},
 
-    {"detect_changes", "Detect changes",
-     "Map a git diff to its BLAST RADIUS. Resolves changed files to the symbols they define, then "
-     "runs ONE multi-source graph traversal to the transitive impact set. RESPONSE: base + "
-     "merge_base SHA, changed_files list, then impacted = prefix-grouped tree rows (name label "
-     "hop; "
-     "full qn = group prefix + dot + name) + an impacted_modules rollup; impacted_total + "
-     "truncated are exact. Seeds (the changed symbols) are excluded from impacted; a changed file "
-     "reached from another changed file is not counted as extra impact. format=\"json\" returns "
-     "the "
-     "same model as structured JSON.",
+    {"detect_changes", "Map a Git diff to files and impact. Page with snapshot cursors.",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},\"scope\":{\"type\":"
-     "\"string\",\"enum\":[\"files\",\"impact\"],\"description\":\"files: changed files only "
-     "(no traversal). impact (default): files + the transitive impact set.\"},"
+     "\"string\",\"enum\":[\"files\",\"impact\"],\"default\":\"impact\"},"
      "\"direction\":{\"type\":\"string\",\"enum\":[\"inbound\",\"outbound\",\"both\"],\"default\":"
-     "\"inbound\",\"description\":\"inbound (default) = the blast radius: transitive CALLERS of "
-     "the "
-     "changed symbols. outbound = what the changed code depends on. both = union.\"},"
-     "\"depth\":{\"type\":\"integer\",\"default\":2,\"description\":\"Max traversal hops from the "
-     "changed symbols.\"},\"limit\":{\"type\":\"integer\",\"default\":200,\"maximum\":5000,"
-     "\"description\":\"Per-symbol impacted rows shown (nearest hops first). impacted_total is "
-     "always exact and the impacted_modules rollup always complete regardless.\"},"
+     "\"inbound\",\"description\":\"inbound=callers; outbound=dependencies; both=union.\"},"
+     "\"depth\":{\"type\":\"integer\",\"default\":2},"
+     "\"limit\":{\"type\":\"integer\",\"default\":200,\"maximum\":5000},"
+     "\"impact_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"impact_cursor\":{\"type\":\"string\"},"
+     "\"changed_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":0,\"maximum\":5000},"
+     "\"changed_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"changed_cursor\":{\"type\":\"string\"},"
+     "\"module_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":0,\"maximum\":256},"
+     "\"module_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"module_cursor\":{\"type\":\"string\"},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"default\":3200,\"minimum\":128,"
+     "\"maximum\":1000000,\"description\":\"Sizing hint; hard ceiling is 4 UTF-8 bytes/token.\"},"
      "\"base_branch\":{\"type\":"
-     "\"string\",\"default\":\"main\"},\"since\":{\"type\":\"string\",\"description\":"
-     "\"Git ref or tag to compare from (e.g. HEAD~5, v0.5.0). Diffs <ref>...HEAD.\"},"
+     "\"string\",\"default\":\"main\"},\"since\":{\"type\":\"string\"},"
      "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
      "\"required\":"
      "[\"project\"]}"},
 
-    {"manage_adr", "Manage ADR", "Create or update Architecture Decision Records",
+    {"manage_adr", "Outline an ADR by default; get reads it; update replaces it",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},\"mode\":{\"type\":"
-     "\"string\",\"enum\":[\"get\",\"update\",\"sections\"],\"description\":\"update replaces "
-     "the entire ADR document; sections only lists existing "
-     "headings\"},\"content\":{\"type\":\"string\",\"description\":\"Complete replacement document "
-     "required by update\"}},\"additionalProperties\":false,"
+     "\"string\",\"enum\":[\"outline\",\"get\",\"update\",\"sections\"],\"default\":\"outline\","
+     "\"description\":\"outline pages headings; get reads; update replaces; sections is legacy.\"},"
+     "\"content\":{\"type\":\"string\"},"
+     "\"section_limit\":{\"type\":\"integer\",\"default\":50,\"minimum\":1,\"maximum\":500},"
+     "\"section_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
+     "\"additionalProperties\":false,"
      "\"required\":[\"project\"]}"},
 
-    {"ingest_traces", "Ingest traces", "Ingest runtime traces to enhance the knowledge graph",
+    {"ingest_traces", "Validate and count traces; graph edge creation is not implemented",
      "{\"type\":\"object\",\"properties\":{\"traces\":{\"type\":\"array\",\"items\":{\"type\":"
      "\"object\",\"properties\":{\"caller\":{\"type\":\"string\"},\"callee\":{\"type\":\"string\"},"
      "\"count\":{\"type\":\"integer\"}},\"additionalProperties\":false}},\"project\":{\"type\":"
@@ -746,7 +760,9 @@ static void mcp_add_json_schema(yyjson_mut_doc *doc, yyjson_mut_val *obj, const
 static void mcp_add_tool_def(yyjson_mut_doc *doc, yyjson_mut_val *tools, int i) {
     yyjson_mut_val *tool = yyjson_mut_obj(doc);
     yyjson_mut_obj_add_str(doc, tool, "name", TOOLS[i].name);
-    yyjson_mut_obj_add_str(doc, tool, "title", TOOLS[i].title);
+    /* MCP title is optional and clients fall back to name. These titles only
+     * repeated the snake_case name with spaces, so omit their recurring
+     * discovery cost and retain the behavioral description instead. */
     yyjson_mut_obj_add_str(doc, tool, "description", TOOLS[i].description);
 
     mcp_add_json_schema(doc, tool, "inputSchema", TOOLS[i].input_schema);
@@ -1231,33 +1247,19 @@ static const int SUPPORTED_VERSION_COUNT =
     (int)(sizeof(SUPPORTED_PROTOCOL_VERSIONS) / sizeof(SUPPORTED_PROTOCOL_VERSIONS[0]));
 
 static const char MCP_SERVER_INSTRUCTIONS[] =
-    "Use graph tools first for structural code discovery: search_graph to find symbols, "
-    "trace_path for callers and callees, get_code_snippet for exact source, query_graph for "
-    "complex multi-hop patterns, and get_architecture for orientation. Use search_code or "
-    "filesystem grep for literal or non-code text, or when graph coverage is insufficient. "
-    "Call list_projects before initial use and index_repository only when a repository is not "
-    "indexed or to force immediate freshness after a large external update. Once indexed, "
-    "watched projects auto-refresh in the background; use index_status for project health and "
-    "check_index_coverage for every cited path and for scopes behind negative or exhaustive "
-    "claims. Coverage is best-effort, never proof of completeness. Check has_more or nextCursor "
-    "and paginate when present.";
+    "Graph first: search_graph for symbols, trace_path for relationships, get_code_snippet for "
+    "source, query_graph for multi-hop, and get_architecture for overview. Use search_code/grep "
+    "for literals or coverage gaps. Indexes auto-refresh. Check cited-path coverage; paginate.";
 
 static const char MCP_ANALYSIS_SERVER_INSTRUCTIONS[] =
-    "This is the analysis tool profile; graph and index mutation tools are unavailable. Use "
-    "list_projects and index_status to select a current graph project, then use search_graph, "
-    "trace_path, get_code_snippet, query_graph, get_architecture, and search_code for read-only "
-    "analysis. Call check_index_coverage for every cited path and for scopes behind negative or "
-    "exhaustive claims; read flagged ranges or skipped files directly. Coverage is best-effort, "
-    "never proof of completeness. Check has_more or nextCursor and paginate when present. If the "
-    "project is missing or stale, ask the parent agent to index or refresh it.";
+    "analysis tool profile: read-only graph work via search_graph, trace_path, "
+    "get_code_snippet, query_graph, get_architecture, or search_code. Use check_index_coverage "
+    "for cited paths; paginate.";
 
 static const char MCP_SCOUT_SERVER_INSTRUCTIONS[] =
-    "This is the scout tool profile; only the fast positive-discovery graph tools are available. "
-    "Use list_projects and index_status to select a current graph project, then use search_graph, "
-    "trace_path, get_code_snippet, and get_architecture with narrow limits. Call "
-    "check_index_coverage once for every cited path and read flagged ranges directly. Findings "
-    "are provisional: do not make absence, exhaustive-impact, or dead-code claims. If the project "
-    "is missing or stale, ask the parent agent to index or refresh it.";
+    "scout tool profile: fast positive discovery via search_graph, trace_path, "
+    "get_code_snippet, or get_architecture with narrow limits. Use check_index_coverage for "
+    "cited paths. Findings are provisional.";
 
 static char *cbm_mcp_initialize_response_for_profile(const char *params_json,
                                                      cbm_mcp_tool_profile_t profile) {
@@ -1536,6 +1538,33 @@ bool cbm_mcp_get_bool_arg(const char *args_json, const char *key) {
     return result;
 }
 
+/* Read tools use a compact tree for the model-facing default. Machine callers
+ * can request format:"json", which preserves the structuredContent fallback
+ * in cbm_mcp_text_result. Keeping this conversion at the final transport edge
+ * avoids maintaining a second semantic response model in each handler. */
+static bool mcp_wants_json(const char *args_json) {
+    char *format = cbm_mcp_get_string_arg(args_json ? args_json : "{}", "format");
+    bool wants_json = format && strcmp(format, "json") == 0;
+    free(format);
+    return wants_json;
+}
+
+static char *mcp_result_from_json(const char *args_json, const char *json) {
+    if (!json) {
+        return cbm_mcp_text_result("out of memory", true);
+    }
+    if (mcp_wants_json(args_json)) {
+        return cbm_mcp_text_result(json, false);
+    }
+    char *tree = cbm_json_to_tree(json);
+    if (!tree) {
+        return cbm_mcp_text_result("failed to render compact output", true);
+    }
+    char *result = cbm_mcp_text_result(tree, false);
+    free(tree);
+    return result;
+}
+
 /* ══════════════════════════════════════════════════════════════════
  *  MCP SERVER
  * ══════════════════════════════════════════════════════════════════ */
@@ -1567,6 +1596,10 @@ struct cbm_mcp_server {
     void *quarantine_test_context;
     cbm_mcp_command_test_hook_fn command_test_hook;
     void *command_test_context;
+#ifdef CBM_ENABLE_TEST_SEAMS
+    cbm_mcp_snapshot_read_test_hook_fn snapshot_read_test_hook;
+    void *snapshot_read_test_context;
+#endif
     cbm_thread_t autoindex_tid;
     bool autoindex_active; /* true if auto-index thread was started */
 
@@ -1865,6 +1898,18 @@ void cbm_mcp_server_set_command_test_hook(cbm_mcp_server_t *srv, cbm_mcp_command
     srv->command_test_context = context;
 }
 
+#ifdef CBM_ENABLE_TEST_SEAMS
+void cbm_mcp_server_set_snapshot_read_test_hook(cbm_mcp_server_t *srv,
+                                                cbm_mcp_snapshot_read_test_hook_fn hook,
+                                                void *context) {
+    if (!srv) {
+        return;
+    }
+    srv->snapshot_read_test_hook = hook;
+    srv->snapshot_read_test_context = context;
+}
+#endif
+
 /* ── Cache dir + project DB path helpers ───────────────────────── */
 
 /* Returns the cache directory. Writes to buf, returns buf for convenience. */
@@ -2494,12 +2539,55 @@ static cbm_store_t *resolve_store_fallback_scan(const char *project) {
     return found;
 }
 
-/* Open a .db file briefly, collect node/edge counts and root_path,
- * then append a JSON entry to arr. */
-static void build_project_json_entry(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *dir_path,
-                                     const char *name, size_t name_len, int64_t size_bytes,
-                                     bool metadata_only) {
-    (void)name_len;
+typedef struct {
+    char *name;
+    char *root_path;
+    char *db_file;
+    char *branch;
+    int nodes;
+    int edges;
+    int64_t size_bytes;
+    bool populated;
+} mcp_project_record_t;
+
+static void project_record_clear(mcp_project_record_t *record) {
+    if (!record) {
+        return;
+    }
+    free(record->name);
+    free(record->root_path);
+    free(record->db_file);
+    free(record->branch);
+    memset(record, 0, sizeof(*record));
+}
+
+static int project_record_compare(const void *left, const void *right) {
+    const mcp_project_record_t *a = left;
+    const mcp_project_record_t *b = right;
+    int by_name = strcmp(a->name ? a->name : "", b->name ? b->name : "");
+    if (by_name != 0) {
+        return by_name;
+    }
+    int by_root = strcmp(a->root_path ? a->root_path : "", b->root_path ? b->root_path : "");
+    if (by_root != 0) {
+        return by_root;
+    }
+    return strcmp(a->db_file ? a->db_file : "", b->db_file ? b->db_file : "");
+}
+
+typedef enum {
+    PROJECT_RECORD_SKIP = 0,
+    PROJECT_RECORD_OK = 1,
+    PROJECT_RECORD_OOM = -1,
+} project_record_status_t;
+
+/* Open a .db file briefly and collect sortable identity only. Counts and Git
+ * context are populated after paging so a 50-row response does not repeat
+ * heavyweight work for every database in the cache. */
+static project_record_status_t read_project_record_identity(const char *dir_path, const char *name,
+                                                            int64_t size_bytes,
+                                                            mcp_project_record_t *record) {
+    memset(record, 0, sizeof(*record));
 
     char full_path[CBM_SZ_2K];
     snprintf(full_path, sizeof(full_path), "%s/%s", dir_path, name);
@@ -2512,44 +2600,90 @@ static void build_project_json_entry(yyjson_mut_doc *doc, yyjson_mut_val *arr, c
     char project_name[CBM_SZ_1K];
     cbm_store_t *pstore = NULL;
     if (!db_internal_project_name(full_path, project_name, sizeof(project_name), &pstore)) {
-        return; /* ghost / unreadable — not a resolvable project */
+        return PROJECT_RECORD_SKIP; /* ghost / unreadable — not resolvable */
     }
 
-    int nodes = 0;
-    int edges = 0;
-    if (!metadata_only) {
-        nodes = cbm_store_count_nodes(pstore, project_name);
-        edges = cbm_store_count_edges(pstore, project_name);
-    }
-    char root_path_buf[CBM_SZ_1K] = "";
+    record->name = heap_strdup(project_name);
+    record->db_file = heap_strdup(name);
+    record->size_bytes = size_bytes;
     cbm_project_t proj = {0};
     if (cbm_store_get_project(pstore, project_name, &proj) == CBM_STORE_OK) {
-        if (proj.root_path) {
-            snprintf(root_path_buf, sizeof(root_path_buf), "%s", proj.root_path);
-        }
+        /* root_path is NOT NULL in the store schema, so a missing copy here is
+         * allocation failure rather than an empty identity. */
+        if (!proj.root_path) {
+            cbm_project_free_fields(&proj);
+            cbm_store_close(pstore);
+            project_record_clear(record);
+            return PROJECT_RECORD_OOM;
+        }
+        /* Store project fields are heap-owned by the caller. Transfer the root
+         * identity intact: it is the value used for sorting, output, and branch
+         * lookup, so routing it through a fixed buffer would silently change
+         * all three for long roots. */
+        record->root_path = (char *)proj.root_path;
+        proj.root_path = NULL;
         cbm_project_free_fields(&proj);
     }
     cbm_store_close(pstore);
+    if (!record->root_path) {
+        record->root_path = heap_strdup("");
+    }
+    if (!record->name || !record->root_path || !record->db_file) {
+        project_record_clear(record);
+        return PROJECT_RECORD_OOM;
+    }
+    return PROJECT_RECORD_OK;
+}
 
-    yyjson_mut_val *p = yyjson_mut_obj(doc);
-    yyjson_mut_obj_add_strcpy(doc, p, "name", project_name);
-    yyjson_mut_obj_add_strcpy(doc, p, "root_path", root_path_buf);
+static bool populate_project_record(const char *dir_path, bool include_stats,
+                                    mcp_project_record_t *record) {
+    if (record->populated) {
+        record->populated = true;
+        return true;
+    }
+    if (include_stats) {
+        char full_path[CBM_SZ_2K];
+        snprintf(full_path, sizeof(full_path), "%s/%s", dir_path, record->db_file);
+        cbm_store_t *pstore = cbm_store_open_path_query(full_path);
+        if (!pstore) {
+            return false;
+        }
+        record->nodes = cbm_store_count_nodes(pstore, record->name);
+        record->edges = cbm_store_count_edges(pstore, record->name);
+        cbm_store_close(pstore);
+    }
     /* Listing stays lean: only the branch (the one git fact that
      * disambiguates same-repo projects). The 12-field git block — mostly
      * null for non-git roots — cost ~10KB across a full cache and is one
      * index_status call away for the project you actually care about. */
-    if (!metadata_only && root_path_buf[0]) {
+    if (record->root_path[0]) {
         cbm_git_context_t gctx = {0};
-        (void)cbm_git_context_resolve(root_path_buf, &gctx);
+        (void)cbm_git_context_resolve(record->root_path, &gctx);
         if (gctx.is_git && gctx.branch) {
-            yyjson_mut_obj_add_strcpy(doc, p, "branch", gctx.branch);
+            record->branch = heap_strdup(gctx.branch);
+            if (!record->branch) {
+                cbm_git_context_free(&gctx);
+                return false;
+            }
         }
         cbm_git_context_free(&gctx);
     }
-    if (!metadata_only) {
-        yyjson_mut_obj_add_int(doc, p, "nodes", nodes);
-        yyjson_mut_obj_add_int(doc, p, "edges", edges);
-        yyjson_mut_obj_add_int(doc, p, "size_bytes", size_bytes);
+    record->populated = true;
+    return true;
+}
+
+static void add_project_record_json(yyjson_mut_doc *doc, yyjson_mut_val *arr,
+                                    const mcp_project_record_t *record, bool include_stats) {
+    yyjson_mut_val *p = yyjson_mut_obj(doc);
+    yyjson_mut_obj_add_strcpy(doc, p, "name", record->name);
+    yyjson_mut_obj_add_strcpy(doc, p, "root_path", record->root_path);
+    if (record->branch) {
+        yyjson_mut_obj_add_strcpy(doc, p, "branch", record->branch);
+    }
+    if (include_stats) {
+        yyjson_mut_obj_add_int(doc, p, "nodes", record->nodes);
+        yyjson_mut_obj_add_int(doc, p, "edges", record->edges);
+        yyjson_mut_obj_add_int(doc, p, "size_bytes", record->size_bytes);
     }
     yyjson_mut_arr_add_val(arr, p);
 }
@@ -2564,6 +2698,9 @@ static char *handle_list_projects(cbm_mcp_server_t *srv, const char *args) {
     yyjson_val *metadata_value =
         args_root && yyjson_is_obj(args_root) ? yyjson_obj_get(args_root, "metadata_only") : NULL;
     metadata_only = metadata_value && yyjson_is_true(metadata_value);
+    char *detail = cbm_mcp_get_string_arg(args, "detail");
+    bool include_stats = !metadata_only && detail && strcmp(detail, "stats") == 0;
+    free(detail);
     if (args_doc) {
         yyjson_doc_free(args_doc);
     }
@@ -2573,21 +2710,19 @@ static char *handle_list_projects(cbm_mcp_server_t *srv, const char *args) {
 
     cbm_dir_t *d = cbm_opendir(dir_path);
 
-    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
-    yyjson_mut_val *root = yyjson_mut_obj(doc);
-    yyjson_mut_doc_set_root(doc, root);
-    yyjson_mut_val *arr = yyjson_mut_arr(doc);
-
     if (!d) {
         char msg[CBM_SZ_1K];
         snprintf(msg, sizeof(msg),
                  "{\"error\":\"cannot read cache directory: %s\",\"hint\":"
                  "\"Check directory permissions or run index_repository first.\"}",
                  dir_path);
-        yyjson_mut_doc_free(doc);
         return cbm_mcp_text_result(msg, true);
     }
 
+    mcp_project_record_t *records = NULL;
+    int record_count = 0;
+    int record_cap = 0;
+    bool oom = false;
     cbm_dirent_t *entry;
     while ((entry = cbm_readdir(d)) != NULL) {
         const char *name = entry->name;
@@ -2601,23 +2736,179 @@ static char *handle_list_projects(cbm_mcp_server_t *srv, const char *args) {
         if (size_bytes < 0) {
             continue;
         }
-        build_project_json_entry(doc, arr, dir_path, name, len, size_bytes, metadata_only);
+        mcp_project_record_t record = {0};
+        project_record_status_t read_status =
+            read_project_record_identity(dir_path, name, size_bytes, &record);
+        if (read_status == PROJECT_RECORD_OOM) {
+            oom = true;
+            break;
+        }
+        if (read_status != PROJECT_RECORD_OK) {
+            continue;
+        }
+        if (record_count == record_cap) {
+            int new_cap = record_cap ? record_cap * 2 : 16;
+            void *grown = realloc(records, (size_t)new_cap * sizeof(*records));
+            if (!grown) {
+                project_record_clear(&record);
+                oom = true;
+                break;
+            }
+            records = grown;
+            record_cap = new_cap;
+        }
+        records[record_count++] = record;
     }
     cbm_closedir(d);
 
-    yyjson_mut_obj_add_val(doc, root, "projects", arr);
+    if (oom) {
+        for (int i = 0; i < record_count; i++) {
+            project_record_clear(&records[i]);
+        }
+        free(records);
+        return cbm_mcp_text_result("out of memory while listing projects", true);
+    }
+    qsort(records, (size_t)record_count, sizeof(*records), project_record_compare);
 
-    /* Guide user when no projects are indexed */
-    if (yyjson_mut_arr_size(arr) == 0) {
-        yyjson_mut_obj_add_str(doc, root, "hint",
-                               "No projects indexed. Call index_repository(repo_path=...) first.");
+    int limit = cbm_mcp_get_int_arg(args, "limit", 50);
+    int offset = cbm_mcp_get_int_arg(args, "offset", 0);
+    if (limit < 1) {
+        limit = 1;
+    } else if (limit > 500) {
+        limit = 500;
+    }
+    if (offset < 0) {
+        offset = 0;
+    }
+    int start = offset < record_count ? offset : record_count;
+    int end = start + limit < record_count ? start + limit : record_count;
+    if (!metadata_only) {
+        for (int i = start; i < end; i++) {
+            if (!populate_project_record(dir_path, include_stats, &records[i])) {
+                oom = true;
+                break;
+            }
+        }
+    }
+    if (oom) {
+        for (int i = 0; i < record_count; i++) {
+            project_record_clear(&records[i]);
+        }
+        free(records);
+        return cbm_mcp_text_result("failed to populate project page", true);
     }
 
-    char *json = yy_doc_to_str(doc);
-    yyjson_mut_doc_free(doc);
+    bool wants_json = mcp_wants_json(args);
+    char *payload = NULL;
+    if (wants_json) {
+        yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+        yyjson_mut_val *root = yyjson_mut_obj(doc);
+        yyjson_mut_doc_set_root(doc, root);
+        yyjson_mut_val *arr = yyjson_mut_arr(doc);
+        for (int i = start; i < end; i++) {
+            add_project_record_json(doc, arr, &records[i], include_stats);
+        }
 
-    char *result = cbm_mcp_text_result(json, false);
-    free(json);
+        yyjson_mut_obj_add_val(doc, root, "projects", arr);
+        yyjson_mut_obj_add_int(doc, root, "total", record_count);
+        yyjson_mut_obj_add_int(doc, root, "returned", end - start);
+        yyjson_mut_obj_add_bool(doc, root, "has_more", end < record_count);
+        if (end < record_count) {
+            yyjson_mut_obj_add_int(doc, root, "next_offset", end);
+        }
+        if (record_count == 0) {
+            yyjson_mut_obj_add_str(
+                doc, root, "hint",
+                "No projects indexed. Call index_repository(repo_path=...) first.");
+        }
+        payload = yy_doc_to_str(doc);
+        yyjson_mut_doc_free(doc);
+    } else {
+        /* Stable union schema: branch is an explicit empty marker instead of
+         * changing each object's shape and forcing the generic tree emitter
+         * to repeat every key. Values and row order remain direct/copyable. */
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        const char *metadata_cols[] = {"name", "root_path"};
+        const char *identity_cols[] = {"name", "root_path", "branch"};
+        const char *stats_cols[] = {"name", "root_path", "branch", "nodes", "edges", "size_bytes"};
+        const char *const *cols = metadata_only   ? metadata_cols
+                                  : include_stats ? stats_cols
+                                                  : identity_cols;
+        int column_count = metadata_only ? 2 : include_stats ? 6 : 3;
+        int page_count = end - start;
+        size_t cell_count = (size_t)page_count * (size_t)column_count;
+        const char **cells = cell_count > 0 && cell_count <= SIZE_MAX / sizeof(*cells)
+                                 ? malloc(cell_count * sizeof(*cells))
+                                 : NULL;
+        char (*numbers)[32] = include_stats && page_count > 0
+                                  ? malloc((size_t)page_count * 3U * sizeof(*numbers))
+                                  : NULL;
+        if (cells && (!include_stats || numbers)) {
+            for (int row = 0; row < page_count; row++) {
+                const mcp_project_record_t *record = &records[start + row];
+                size_t base = (size_t)row * (size_t)column_count;
+                cells[base] = record->name;
+                cells[base + 1U] = record->root_path;
+                if (!metadata_only) {
+                    cells[base + 2U] = record->branch ? record->branch : "";
+                }
+                if (include_stats) {
+                    size_t number_base = (size_t)row * 3U;
+                    snprintf(numbers[number_base], sizeof(numbers[number_base]), "%d",
+                             record->nodes);
+                    snprintf(numbers[number_base + 1U], sizeof(numbers[number_base + 1U]), "%d",
+                             record->edges);
+                    snprintf(numbers[number_base + 2U], sizeof(numbers[number_base + 2U]), "%lld",
+                             (long long)record->size_bytes);
+                    cells[base + 3U] = numbers[number_base];
+                    cells[base + 4U] = numbers[number_base + 1U];
+                    cells[base + 5U] = numbers[number_base + 2U];
+                }
+            }
+            const bool string_cols[] = {true, true, true, false, false, false};
+            const bool prefix_cols[] = {false, true, false, false, false, false};
+            cbm_tree_table_rows_profiled(&sb, "projects", page_count, cols, column_count, cells,
+                                         string_cols, prefix_cols);
+        } else {
+            cbm_tree_table_header(&sb, "projects", page_count, cols, column_count);
+            for (int i = start; i < end; i++) {
+                cbm_tree_row_begin(&sb);
+                cbm_tree_cell_str(&sb, records[i].name, true);
+                cbm_tree_cell_str(&sb, records[i].root_path, false);
+                if (!metadata_only) {
+                    cbm_tree_cell_str(&sb, records[i].branch ? records[i].branch : "", false);
+                }
+                if (include_stats) {
+                    cbm_tree_cell_int(&sb, records[i].nodes, false);
+                    cbm_tree_cell_int(&sb, records[i].edges, false);
+                    cbm_tree_cell_int(&sb, (long long)records[i].size_bytes, false);
+                }
+                cbm_tree_row_end(&sb);
+            }
+        }
+        free(numbers);
+        free(cells);
+        cbm_tree_scalar_int(&sb, "total", record_count);
+        cbm_tree_scalar_int(&sb, "returned", end - start);
+        cbm_tree_scalar_bool(&sb, "has_more", end < record_count);
+        if (end < record_count) {
+            cbm_tree_scalar_int(&sb, "next_offset", end);
+        }
+        if (record_count == 0) {
+            cbm_tree_scalar_str(&sb, "hint",
+                                "No projects indexed. Call index_repository(repo_path=...) first.");
+        }
+        payload = cbm_sb_finish(&sb);
+    }
+
+    for (int i = 0; i < record_count; i++) {
+        project_record_clear(&records[i]);
+    }
+    free(records);
+
+    char *result = cbm_mcp_text_result(payload ? payload : "out of memory", payload == NULL);
+    free(payload);
     return result;
 }
 
@@ -2643,6 +2934,25 @@ static char *verify_project_indexed(cbm_store_t *store, const char *project) {
 
 static bool sg_field_blocked(const char *f); /* internal-only fields, defined with search_graph */
 
+typedef struct {
+    bool node;
+    int index;
+    int count;
+    const char *name;
+} mcp_schema_record_t;
+
+static int schema_record_compare(const void *left, const void *right) {
+    const mcp_schema_record_t *a = left;
+    const mcp_schema_record_t *b = right;
+    if (a->node != b->node) {
+        return a->node ? -1 : 1;
+    }
+    if (a->count != b->count) {
+        return a->count > b->count ? -1 : 1;
+    }
+    return strcmp(a->name ? a->name : "", b->name ? b->name : "");
+}
+
 static char *handle_get_graph_schema(cbm_mcp_server_t *srv, const char *args) {
     char *project = get_project_arg(args);
     cbm_store_t *store = resolve_store(srv, project);
@@ -2654,54 +2964,108 @@ static char *handle_get_graph_schema(cbm_mcp_server_t *srv, const char *args) {
         return not_indexed;
     }
 
+    char *diagnostics = cbm_mcp_get_string_arg(args, "diagnostics");
+    bool include_properties = diagnostics && strcmp(diagnostics, "full") == 0;
+    free(diagnostics);
+
     cbm_schema_info_t schema = {0};
-    cbm_store_get_schema(store, project, &schema);
+    if (include_properties) {
+        cbm_store_get_schema(store, project, &schema);
+    } else {
+        cbm_store_get_schema_counts(store, project, &schema);
+    }
+
+    int limit = cbm_mcp_get_int_arg(args, "limit", 50);
+    int offset = cbm_mcp_get_int_arg(args, "offset", 0);
+    if (limit < 1) {
+        limit = 1;
+    } else if (limit > 500) {
+        limit = 500;
+    }
+    if (offset < 0) {
+        offset = 0;
+    }
+    int total = schema.node_label_count + schema.edge_type_count;
+    size_t record_capacity = total > 0 ? (size_t)total : 1U;
+    mcp_schema_record_t *records = calloc(record_capacity, sizeof(*records));
+    if (!records) {
+        cbm_store_schema_free(&schema);
+        free(project);
+        return cbm_mcp_text_result("out of memory while rendering schema", true);
+    }
+    int record_count = 0;
+    for (int i = 0; i < schema.node_label_count; i++) {
+        records[record_count++] = (mcp_schema_record_t){true, i, schema.node_labels[i].count,
+                                                        schema.node_labels[i].label};
+    }
+    for (int i = 0; i < schema.edge_type_count; i++) {
+        records[record_count++] =
+            (mcp_schema_record_t){false, i, schema.edge_types[i].count, schema.edge_types[i].type};
+    }
+    qsort(records, (size_t)record_count, sizeof(*records), schema_record_compare);
+    int start = offset < total ? offset : total;
+    int end = start + limit < total ? start + limit : total;
 
     yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
     yyjson_mut_val *root = yyjson_mut_obj(doc);
     yyjson_mut_doc_set_root(doc, root);
 
     yyjson_mut_val *labels = yyjson_mut_arr(doc);
-    for (int i = 0; i < schema.node_label_count; i++) {
+    for (int page = start; page < end; page++) {
+        if (!records[page].node) {
+            continue;
+        }
+        int i = records[page].index;
         yyjson_mut_val *lbl = yyjson_mut_obj(doc);
         yyjson_mut_obj_add_str(doc, lbl, "label", schema.node_labels[i].label);
         yyjson_mut_obj_add_int(doc, lbl, "count", schema.node_labels[i].count);
-        yyjson_mut_val *props = yyjson_mut_arr(doc);
-        for (int j = 0; j < schema.node_labels[i].property_count; j++) {
-            /* Internal similarity intermediates (fp/sp/bt) are blocked from every
-             * tool response — advertising them here invited agents to request
-             * fields the server then silently refuses. Filter them from the
-             * schema so it only describes obtainable properties. */
-            if (sg_field_blocked(schema.node_labels[i].properties[j])) {
-                continue;
+        if (include_properties) {
+            yyjson_mut_val *props = yyjson_mut_arr(doc);
+            for (int j = 0; j < schema.node_labels[i].property_count; j++) {
+                /* Internal similarity intermediates are never public. */
+                if (sg_field_blocked(schema.node_labels[i].properties[j])) {
+                    continue;
+                }
+                yyjson_mut_arr_add_str(doc, props, schema.node_labels[i].properties[j]);
             }
-            yyjson_mut_arr_add_str(doc, props, schema.node_labels[i].properties[j]);
+            yyjson_mut_obj_add_val(doc, lbl, "properties", props);
         }
-        yyjson_mut_obj_add_val(doc, lbl, "properties", props);
         yyjson_mut_arr_add_val(labels, lbl);
     }
     yyjson_mut_obj_add_val(doc, root, "node_labels", labels);
 
     yyjson_mut_val *types = yyjson_mut_arr(doc);
-    for (int i = 0; i < schema.edge_type_count; i++) {
+    for (int page = start; page < end; page++) {
+        if (records[page].node) {
+            continue;
+        }
+        int i = records[page].index;
         yyjson_mut_val *typ = yyjson_mut_obj(doc);
         yyjson_mut_obj_add_str(doc, typ, "type", schema.edge_types[i].type);
         yyjson_mut_obj_add_int(doc, typ, "count", schema.edge_types[i].count);
-        yyjson_mut_val *eprops = yyjson_mut_arr(doc);
-        for (int j = 0; j < schema.edge_types[i].property_count; j++) {
-            yyjson_mut_arr_add_str(doc, eprops, schema.edge_types[i].properties[j]);
+        if (include_properties) {
+            yyjson_mut_val *eprops = yyjson_mut_arr(doc);
+            for (int j = 0; j < schema.edge_types[i].property_count; j++) {
+                yyjson_mut_arr_add_str(doc, eprops, schema.edge_types[i].properties[j]);
+            }
+            yyjson_mut_obj_add_val(doc, typ, "properties", eprops);
         }
-        yyjson_mut_obj_add_val(doc, typ, "properties", eprops);
         yyjson_mut_arr_add_val(types, typ);
     }
     yyjson_mut_obj_add_val(doc, root, "edge_types", types);
+    yyjson_mut_obj_add_int(doc, root, "total", total);
+    yyjson_mut_obj_add_int(doc, root, "returned", end - start);
+    yyjson_mut_obj_add_bool(doc, root, "has_more", end < total);
+    if (end < total) {
+        yyjson_mut_obj_add_int(doc, root, "next_offset", end);
+    }
 
     /* Check ADR presence */
     cbm_project_t proj_info = {0};
     if (cbm_store_get_project(store, project, &proj_info) == 0 && proj_info.root_path) {
         bool adr_exists = project_has_adr(store, project, proj_info.root_path);
         yyjson_mut_obj_add_bool(doc, root, "adr_present", adr_exists);
-        if (!adr_exists) {
+        if (!adr_exists && include_properties) {
             yyjson_mut_obj_add_str(
                 doc, root, "adr_hint",
                 "No ADR found. Use manage_adr(mode='update') to persist architectural "
@@ -2712,10 +3076,11 @@ static char *handle_get_graph_schema(cbm_mcp_server_t *srv, const char *args) {
 
     char *json = yy_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
+    free(records);
     cbm_store_schema_free(&schema);
     free(project);
 
-    char *result = cbm_mcp_text_result(json, false);
+    char *result = mcp_result_from_json(args, json);
     free(json);
     return result;
 }
@@ -2765,31 +3130,32 @@ static yyjson_mut_val *enrich_connected(yyjson_mut_doc *doc, cbm_store_t *store,
     return conn;
 }
 
-/* Text-tree variant: the same 1-hop neighbor names ';'-joined into buf (no
- * commas/spaces in names, so the cell needs no quoting). Empty when none. */
-static void enrich_connected_joined(cbm_store_t *store, int64_t node_id, const char *relationship,
-                                    char *buf, size_t bufsz) {
-    buf[0] = '\0';
+/* Text-tree variant: the same 1-hop neighbor names joined without a fixed
+ * staging buffer. Identifiers are semantic atoms: emit each in full or omit
+ * the entire connected column at the response-budget layer. */
+static char *enrich_connected_joined(cbm_store_t *store, int64_t node_id,
+                                     const char *relationship) {
     const char *et[] = {relationship ? relationship : "CALLS"};
-    size_t off = 0;
+    cbm_sb_t sb;
+    cbm_sb_init(&sb);
+    bool any = false;
     const char *dirs[2] = {"inbound", "outbound"};
     for (int d = 0; d < 2; d++) {
         cbm_traverse_result_t tr = {0};
         cbm_store_bfs(store, node_id, dirs[d], et, SKIP_ONE, SKIP_ONE, MCP_DEFAULT_LIMIT, &tr);
-        for (int j = 0; j < tr.visited_count && off + 2 < bufsz; j++) {
+        for (int j = 0; j < tr.visited_count; j++) {
             if (!tr.visited[j].node.name) {
                 continue;
             }
-            int n =
-                snprintf(buf + off, bufsz - off, "%s%s", off ? ";" : "", tr.visited[j].node.name);
-            if (n < 0 || (size_t)n >= bufsz - off) {
-                buf[off] = '\0';
-                break;
+            if (any) {
+                cbm_sb_append(&sb, ";");
             }
-            off += (size_t)n;
+            cbm_sb_append(&sb, tr.visited[j].node.name);
+            any = true;
         }
         cbm_store_traverse_free(&tr);
     }
+    return cbm_sb_finish(&sb);
 }
 
 /* Build an FTS5 MATCH expression from a free-form query string by splitting
@@ -2895,60 +3261,216 @@ static char *bm25_file_pattern_like(const char *file_pattern) {
     return like;
 }
 
-/* Run the BM25 full-text search path and return the JSON result string.
- * Returns NULL if FTS5 is unavailable or the query produced no usable tokens,
- * in which case the caller falls back to the regex-based search path. */
-static char *bm25_search(cbm_store_t *store, const char *project, const char *query,
-                         const char *file_pattern, int limit, int offset, bool toon) {
-    sqlite3 *db = cbm_store_get_db(store);
-    if (!db) {
-        return NULL;
+typedef struct {
+    char *qualified_name;
+    char *label;
+    char *file_path;
+    int start_line;
+    int end_line;
+    double rank;
+} bm25_output_row_t;
+
+static void bm25_output_rows_free(bm25_output_row_t *rows, int count) {
+    if (!rows) {
+        return;
     }
-    char fts_query[BM25_QUERY_BUF];
-    int tok_count = bm25_build_match(query, fts_query, sizeof(fts_query));
-    if (tok_count == 0) {
-        return NULL;
+    for (int i = 0; i < count; i++) {
+        free(rows[i].qualified_name);
+        free(rows[i].label);
+        free(rows[i].file_path);
     }
-    char *file_like = bm25_file_pattern_like(file_pattern);
-
-    /* BM25 ranked query using a two-step approach to enable FTS5 early termination.
-     *
-     * Flat queries of the form:
-     *   SELECT ... FROM nodes_fts JOIN nodes WHERE MATCH ? AND n.project=? ORDER BY rank LIMIT N
-     * block FTS5's WAND/MaxScore early-exit because the outer JOIN+WHERE conditions
-     * are invisible to the FTS5 planner — it must score every matching document before
-     * the project/label filter can discard any of them.  On a large codebase with 100K+
-     * matches, this causes multi-minute queries.
-     *
-     * The fix: let FTS5 drive the inner subquery alone.  SQLite CAN early-terminate
-     *   SELECT rowid, bm25(nodes_fts) FROM nodes_fts WHERE MATCH ? ORDER BY bm25() LIMIT N
-     * because no outer predicate blocks it.  We fetch BM25_INNER_LIMIT top candidates
-     * from the FTS5 index, then join/filter/boost only those rows.  bm25() returns a
-     * NEGATIVE score (lower = more relevant). */
-    const char *sql =
-        "SELECT n.id, n.label, n.name, n.qualified_name, n.file_path, n.start_line, n.end_line, "
-        "       (fts.base_rank "
-        "        - CASE WHEN n.label IN ('Function','Method') THEN 10.0 "
-        "               WHEN n.label = 'Route' THEN 8.0 "
-        "               WHEN n.label IN (" CBM_SQL_TYPE_LIKE_LABELS ") THEN 5.0 "
-        "               ELSE 0.0 END) AS rank "
-        "FROM ("
-        "    SELECT rowid, bm25(nodes_fts) AS base_rank"
-        "    FROM nodes_fts WHERE nodes_fts MATCH ?1"
-        "    ORDER BY base_rank LIMIT ?5"
-        ") fts "
-        "JOIN nodes n ON n.id = fts.rowid "
-        "WHERE n.project = ?2 "
-        "  AND n.label NOT IN ('File','Folder','Module','Section','Variable','Project') "
-        "  AND (?6 IS NULL OR n.file_path LIKE ?6) "
-        /* rank ties are common (boosted floats) — the id tie-break makes
-         * offset pages contractually stable across calls. */
-        "ORDER BY rank, n.id "
-        "LIMIT ?3 OFFSET ?4";
+    free(rows);
+}
 
-    sqlite3_stmt *stmt = NULL;
-    if (sqlite3_prepare_v2(db, sql, BM25_SQL_AUTO_LEN, &stmt, NULL) != SQLITE_OK) {
-        free(file_like);
+static void bm25_lines_str(char *out, size_t size, int start, int end) {
+    if (start > 0) {
+        snprintf(out, size, "%d-%d", start, end > start ? end : start);
+    } else {
+        out[0] = '\0';
+    }
+}
+
+static void bm25_emit_metadata_tree(cbm_sb_t *sb, int total, int offset, int returned,
+                                    bool candidate_window_saturated, bool budget_hit,
+                                    bool floor_exceeded, size_t max_output_bytes) {
+    bool has_more = total > offset + returned;
+    cbm_tree_scalar_int(sb, "total", total);
+    cbm_tree_scalar_str(sb, "total_relation", candidate_window_saturated ? "gte" : "eq");
+    if (candidate_window_saturated) {
+        cbm_tree_scalar_bool(sb, "candidate_window_saturated", true);
+    }
+    cbm_tree_scalar_str(sb, "search_mode", "bm25");
+    cbm_tree_scalar_int(sb, "returned", returned);
+    cbm_tree_scalar_bool(sb, "has_more", has_more);
+    if (has_more && returned > 0) {
+        cbm_tree_scalar_int(sb, "next_offset", offset + returned);
+    } else if (has_more) {
+        cbm_tree_scalar_bool(sb, "continuation_requires_higher_budget", true);
+    }
+    bool truncated = has_more || candidate_window_saturated || budget_hit;
+    cbm_tree_scalar_bool(sb, "truncated", truncated);
+    if (truncated) {
+        const char *reason = budget_hit ? "output_budget"
+                             : has_more ? "page_limit"
+                                        : "candidate_window";
+        cbm_tree_scalar_str(sb, "truncation_reason", reason);
+    }
+    if (budget_hit) {
+        cbm_tree_scalar_int(sb, "max_output_bytes", (long long)max_output_bytes);
+    }
+    if (floor_exceeded) {
+        cbm_tree_scalar_bool(sb, "output_budget_floor_exceeded", true);
+        cbm_tree_scalar_str(sb, "hint",
+                            "first identity row exceeds max_output_bytes; raise "
+                            "max_output_tokens");
+    }
+}
+
+static void bm25_emit_metadata_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int total,
+                                    int offset, int returned, bool candidate_window_saturated,
+                                    bool budget_hit, bool floor_exceeded, size_t max_output_bytes) {
+    bool has_more = total > offset + returned;
+    yyjson_mut_obj_add_int(doc, root, "total", total);
+    yyjson_mut_obj_add_str(doc, root, "total_relation", candidate_window_saturated ? "gte" : "eq");
+    if (candidate_window_saturated) {
+        yyjson_mut_obj_add_bool(doc, root, "candidate_window_saturated", true);
+    }
+    yyjson_mut_obj_add_str(doc, root, "search_mode", "bm25");
+    yyjson_mut_obj_add_int(doc, root, "returned", returned);
+    yyjson_mut_obj_add_int(doc, root, "count", returned);
+    yyjson_mut_obj_add_bool(doc, root, "has_more", has_more);
+    if (has_more && returned > 0) {
+        yyjson_mut_obj_add_int(doc, root, "next_offset", offset + returned);
+    } else if (has_more) {
+        yyjson_mut_obj_add_bool(doc, root, "continuation_requires_higher_budget", true);
+    }
+    bool truncated = has_more || candidate_window_saturated || budget_hit;
+    yyjson_mut_obj_add_bool(doc, root, "truncated", truncated);
+    if (truncated) {
+        const char *reason = budget_hit ? "output_budget"
+                             : has_more ? "page_limit"
+                                        : "candidate_window";
+        yyjson_mut_obj_add_str(doc, root, "truncation_reason", reason);
+    }
+    if (budget_hit) {
+        yyjson_mut_obj_add_uint(doc, root, "max_output_bytes", max_output_bytes);
+    }
+    if (floor_exceeded) {
+        yyjson_mut_obj_add_bool(doc, root, "output_budget_floor_exceeded", true);
+        yyjson_mut_obj_add_str(doc, root, "hint",
+                               "first identity row exceeds max_output_bytes; raise "
+                               "max_output_tokens");
+    }
+}
+
+static char *bm25_render(const bm25_output_row_t *rows, int returned, int total, int offset,
+                         bool candidate_window_saturated, bool tree_format, bool budget_hit,
+                         bool floor_exceeded, size_t max_output_bytes) {
+    if (tree_format) {
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        static const char *const cols[] = {"qn", "label", "file", "lines", "rank"};
+        cbm_tree_table_header(&sb, "results", returned, cols, 5);
+        for (int i = 0; i < returned; i++) {
+            char lines[CBM_SZ_32];
+            bm25_lines_str(lines, sizeof(lines), rows[i].start_line, rows[i].end_line);
+            cbm_tree_row_begin(&sb);
+            cbm_tree_cell_str(&sb, rows[i].qualified_name, true);
+            cbm_tree_cell_str(&sb, rows[i].label, false);
+            cbm_tree_cell_str(&sb, rows[i].file_path, false);
+            cbm_tree_cell_str(&sb, lines, false);
+            cbm_tree_cell_real(&sb, rows[i].rank, false);
+            cbm_tree_row_end(&sb);
+        }
+        bm25_emit_metadata_tree(&sb, total, offset, returned, candidate_window_saturated,
+                                budget_hit, floor_exceeded, max_output_bytes);
+        return cbm_sb_finish(&sb);
+    }
+
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *root = yyjson_mut_obj(doc);
+    yyjson_mut_doc_set_root(doc, root);
+    yyjson_mut_val *cols = yyjson_mut_arr(doc);
+    static const char *const col_names[] = {"qn", "label", "file", "lines", "rank"};
+    for (size_t i = 0; i < sizeof(col_names) / sizeof(col_names[0]); i++) {
+        yyjson_mut_arr_add_str(doc, cols, col_names[i]);
+    }
+    yyjson_mut_obj_add_val(doc, root, "cols", cols);
+    yyjson_mut_val *result_rows = yyjson_mut_arr(doc);
+    for (int i = 0; i < returned; i++) {
+        char lines[CBM_SZ_32];
+        bm25_lines_str(lines, sizeof(lines), rows[i].start_line, rows[i].end_line);
+        yyjson_mut_val *row = yyjson_mut_arr(doc);
+        yyjson_mut_arr_add_strcpy(doc, row, rows[i].qualified_name);
+        yyjson_mut_arr_add_strcpy(doc, row, rows[i].label);
+        yyjson_mut_arr_add_strcpy(doc, row, rows[i].file_path);
+        yyjson_mut_arr_add_strcpy(doc, row, lines);
+        yyjson_mut_arr_add_real(doc, row, rows[i].rank);
+        yyjson_mut_arr_add_val(result_rows, row);
+    }
+    yyjson_mut_obj_add_val(doc, root, "rows", result_rows);
+    bm25_emit_metadata_json(doc, root, total, offset, returned, candidate_window_saturated,
+                            budget_hit, floor_exceeded, max_output_bytes);
+    char *json = yy_doc_to_str(doc);
+    yyjson_mut_doc_free(doc);
+    return json;
+}
+
+/* Run the BM25 full-text search path and return the JSON result string.
+ * Returns NULL if FTS5 is unavailable or the query produced no usable tokens,
+ * in which case the caller falls back to the regex-based search path. */
+static char *bm25_search(cbm_store_t *store, const char *project, const char *query,
+                         const char *file_pattern, int limit, int offset, bool tree_format,
+                         size_t max_output_bytes) {
+    sqlite3 *db = cbm_store_get_db(store);
+    if (!db) {
+        return NULL;
+    }
+    char fts_query[BM25_QUERY_BUF];
+    int tok_count = bm25_build_match(query, fts_query, sizeof(fts_query));
+    if (tok_count == 0) {
+        return NULL;
+    }
+    char *file_like = bm25_file_pattern_like(file_pattern);
+
+    /* BM25 ranked query using a two-step approach to enable FTS5 early termination.
+     *
+     * Flat queries of the form:
+     *   SELECT ... FROM nodes_fts JOIN nodes WHERE MATCH ? AND n.project=? ORDER BY rank LIMIT N
+     * block FTS5's WAND/MaxScore early-exit because the outer JOIN+WHERE conditions
+     * are invisible to the FTS5 planner — it must score every matching document before
+     * the project/label filter can discard any of them.  On a large codebase with 100K+
+     * matches, this causes multi-minute queries.
+     *
+     * The fix: let FTS5 drive the inner subquery alone.  SQLite CAN early-terminate
+     *   SELECT rowid, bm25(nodes_fts) FROM nodes_fts WHERE MATCH ? ORDER BY bm25() LIMIT N
+     * because no outer predicate blocks it.  We fetch BM25_INNER_LIMIT top candidates
+     * from the FTS5 index, then join/filter/boost only those rows.  bm25() returns a
+     * NEGATIVE score (lower = more relevant). */
+    const char *sql =
+        "SELECT n.id, n.label, n.name, n.qualified_name, n.file_path, n.start_line, n.end_line, "
+        "       (fts.base_rank "
+        "        - CASE WHEN n.label IN ('Function','Method') THEN 10.0 "
+        "               WHEN n.label = 'Route' THEN 8.0 "
+        "               WHEN n.label IN (" CBM_SQL_TYPE_LIKE_LABELS ") THEN 5.0 "
+        "               ELSE 0.0 END) AS rank "
+        "FROM ("
+        "    SELECT rowid, bm25(nodes_fts) AS base_rank"
+        "    FROM nodes_fts WHERE nodes_fts MATCH ?1"
+        "    ORDER BY base_rank, rowid LIMIT ?5"
+        ") fts "
+        "JOIN nodes n ON n.id = fts.rowid "
+        "WHERE n.project = ?2 "
+        "  AND n.label NOT IN ('File','Folder','Module','Section','Variable','Project') "
+        "  AND (?6 IS NULL OR n.file_path LIKE ?6) "
+        /* rank ties are common (boosted floats) — the id tie-break makes
+         * offset pages contractually stable across calls. */
+        "ORDER BY rank, n.id "
+        "LIMIT ?3 OFFSET ?4";
+
+    sqlite3_stmt *stmt = NULL;
+    if (sqlite3_prepare_v2(db, sql, BM25_SQL_AUTO_LEN, &stmt, NULL) != SQLITE_OK) {
+        free(file_like);
         return NULL;
     }
     sqlite3_bind_text(stmt, BM25_BIND_QUERY, fts_query, BM25_SQL_AUTO_LEN, MCP_SQLITE_TRANSIENT);
@@ -2970,7 +3492,7 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
             "SELECT COUNT(*) FROM ("
             "    SELECT fts.rowid FROM ("
             "        SELECT rowid FROM nodes_fts WHERE nodes_fts MATCH ?1"
-            "        ORDER BY bm25(nodes_fts) LIMIT ?3"
+            "        ORDER BY bm25(nodes_fts), rowid LIMIT ?3"
             "    ) fts "
             "    JOIN nodes n ON n.id = fts.rowid "
             "    WHERE n.project = ?2 "
@@ -2997,91 +3519,70 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
         }
     }
 
-    if (toon) {
-        /* TOON: rows are buffered first because the table header carries the
-         * row count, which sqlite only yields by stepping to completion. */
-        cbm_sb_t rows;
-        cbm_sb_init(&rows);
-        int emitted = 0;
-        while (sqlite3_step(stmt) == SQLITE_ROW) {
-            char lines[CBM_SZ_32];
-            int sl = sqlite3_column_int(stmt, BM25_COL_START);
-            int el = sqlite3_column_int(stmt, BM25_COL_END);
-            if (sl > 0) {
-                snprintf(lines, sizeof(lines), "%d-%d", sl, el > sl ? el : sl);
-            } else {
-                lines[0] = '\0';
-            }
-            cbm_tree_row_begin(&rows);
-            cbm_tree_cell_str(&rows, (const char *)sqlite3_column_text(stmt, BM25_COL_QN), true);
-            cbm_tree_cell_str(&rows, (const char *)sqlite3_column_text(stmt, BM25_COL_LABEL),
-                              false);
-            cbm_tree_cell_str(&rows, (const char *)sqlite3_column_text(stmt, BM25_COL_FILE), false);
-            cbm_tree_cell_str(&rows, lines, false);
-            cbm_tree_cell_real(&rows, sqlite3_column_double(stmt, BM25_COL_RANK), false);
-            cbm_tree_row_end(&rows);
-            emitted++;
-        }
-        sqlite3_finalize(stmt);
-        free(file_like);
-
-        cbm_sb_t sb;
-        cbm_sb_init(&sb);
-        cbm_tree_scalar_int(&sb, "total", total);
-        cbm_tree_scalar_str(&sb, "search_mode", "bm25");
-        static const char *const cols[] = {"qn", "label", "file", "lines", "rank"};
-        cbm_tree_table_header(&sb, "results", emitted, cols, 5);
-        char *rows_text = cbm_sb_finish(&rows);
-        cbm_sb_append(&sb, rows_text ? rows_text : "");
-        free(rows_text);
-        cbm_tree_scalar_bool(&sb, "has_more", total > offset + emitted);
-        return cbm_sb_finish(&sb);
+    /* The top-candidate window is a performance ceiling, not an exact-total
+     * boundary. Probe one candidate beyond it so a broad query never presents
+     * a window-local count as the complete match count. This is global to the
+     * FTS table; saturation is therefore conservatively reported even when
+     * later project/path filters might discard the hidden candidates. */
+    bool candidate_window_saturated = true;
+    {
+        const char *probe_sql = "SELECT rowid FROM nodes_fts WHERE nodes_fts MATCH ?1 "
+                                "ORDER BY bm25(nodes_fts), rowid LIMIT 1 OFFSET ?2";
+        sqlite3_stmt *probe = NULL;
+        if (sqlite3_prepare_v2(db, probe_sql, BM25_SQL_AUTO_LEN, &probe, NULL) == SQLITE_OK) {
+            sqlite3_bind_text(probe, BM25_BIND_QUERY, fts_query, BM25_SQL_AUTO_LEN,
+                              MCP_SQLITE_TRANSIENT);
+            sqlite3_bind_int(probe, BM25_BIND_PROJECT, BM25_INNER_LIMIT);
+            int probe_step = sqlite3_step(probe);
+            candidate_window_saturated = probe_step != SQLITE_DONE;
+            sqlite3_finalize(probe);
+        }
+    }
+
+    int row_cap = limit > 0 ? limit : BM25_DEFAULT_LIMIT;
+    bm25_output_row_t *rows = calloc((size_t)row_cap, sizeof(*rows));
+    int row_count = 0;
+    while (rows && row_count < row_cap && sqlite3_step(stmt) == SQLITE_ROW) {
+        const char *qn = (const char *)sqlite3_column_text(stmt, BM25_COL_QN);
+        const char *label = (const char *)sqlite3_column_text(stmt, BM25_COL_LABEL);
+        const char *file = (const char *)sqlite3_column_text(stmt, BM25_COL_FILE);
+        rows[row_count].qualified_name = heap_strdup(qn ? qn : "");
+        rows[row_count].label = heap_strdup(label ? label : "");
+        rows[row_count].file_path = heap_strdup(file ? file : "");
+        rows[row_count].start_line = sqlite3_column_int(stmt, BM25_COL_START);
+        rows[row_count].end_line = sqlite3_column_int(stmt, BM25_COL_END);
+        rows[row_count].rank = sqlite3_column_double(stmt, BM25_COL_RANK);
+        row_count++;
     }
+    sqlite3_finalize(stmt);
+    free(file_like);
 
-    /* format:"json" = json-stringified tree: cols + column-ordered row
-     * arrays (rank order preserved — no grouping on ranked output). */
-    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
-    yyjson_mut_val *root = yyjson_mut_obj(doc);
-    yyjson_mut_doc_set_root(doc, root);
-    yyjson_mut_obj_add_int(doc, root, "total", total);
-    yyjson_mut_obj_add_str(doc, root, "search_mode", "bm25");
-    yyjson_mut_val *jcols = yyjson_mut_arr(doc);
-    static const char *const bm25_cols[] = {"qn", "label", "file", "lines", "rank"};
-    for (size_t ci = 0; ci < sizeof(bm25_cols) / sizeof(bm25_cols[0]); ci++) {
-        yyjson_mut_arr_add_str(doc, jcols, bm25_cols[ci]);
+    if (!rows) {
+        return heap_strdup("out of memory");
     }
-    yyjson_mut_obj_add_val(doc, root, "cols", jcols);
 
-    yyjson_mut_val *rows = yyjson_mut_arr(doc);
-    int emitted = 0;
-    while (sqlite3_step(stmt) == SQLITE_ROW) {
-        char lines[CBM_SZ_32];
-        int sl = sqlite3_column_int(stmt, BM25_COL_START);
-        int el = sqlite3_column_int(stmt, BM25_COL_END);
-        if (sl > 0) {
-            snprintf(lines, sizeof(lines), "%d-%d", sl, el > sl ? el : sl);
-        } else {
-            lines[0] = '\0';
+    int returned = row_count;
+    bool budget_hit = false;
+    char *payload = NULL;
+    for (;;) {
+        payload = bm25_render(rows, returned, total, offset, candidate_window_saturated,
+                              tree_format, budget_hit, false, max_output_bytes);
+        if (!payload || strlen(payload) <= max_output_bytes || returned == 0) {
+            break;
         }
-        yyjson_mut_val *row = yyjson_mut_arr(doc);
-        yyjson_mut_arr_add_strcpy(doc, row, (const char *)sqlite3_column_text(stmt, BM25_COL_QN));
-        yyjson_mut_arr_add_strcpy(doc, row,
-                                  (const char *)sqlite3_column_text(stmt, BM25_COL_LABEL));
-        yyjson_mut_arr_add_strcpy(doc, row, (const char *)sqlite3_column_text(stmt, BM25_COL_FILE));
-        yyjson_mut_arr_add_strcpy(doc, row, lines);
-        yyjson_mut_arr_add_real(doc, row, sqlite3_column_double(stmt, BM25_COL_RANK));
-        yyjson_mut_arr_add_val(rows, row);
-        emitted++;
+        free(payload);
+        payload = NULL;
+        budget_hit = true;
+        returned--;
     }
-    sqlite3_finalize(stmt);
-    free(file_like);
-
-    yyjson_mut_obj_add_val(doc, root, "rows", rows);
-    yyjson_mut_obj_add_bool(doc, root, "has_more", total > offset + emitted);
 
-    char *json = yy_doc_to_str(doc);
-    yyjson_mut_doc_free(doc);
-    return json;
+    if (!payload || strlen(payload) > max_output_bytes || (row_count > 0 && returned == 0)) {
+        free(payload);
+        payload = bm25_render(rows, 0, total, offset, candidate_window_saturated, tree_format, true,
+                              row_count > 0, max_output_bytes);
+    }
+    bm25_output_rows_free(rows, row_count);
+    return payload;
 }
 
 /* Extract keyword strings from a yyjson array into `keywords`.  Returns the
@@ -3106,7 +3607,7 @@ static int extract_semantic_keywords(yyjson_val *sq_val, const char **keywords,
 /* Emit vector-search hits in the json-tree model: "semantic": {cols, rows}
  * — score order preserved (ranked output is never regrouped). */
 static void emit_semantic_results(yyjson_mut_doc *doc, yyjson_mut_val *root,
-                                  cbm_vector_result_t *vresults, int vcount) {
+                                  const cbm_vector_result_t *vresults, int returned) {
     yyjson_mut_val *sem = yyjson_mut_obj(doc);
     yyjson_mut_val *scols = yyjson_mut_arr(doc);
     static const char *const sem_cols[] = {"qn", "label", "file", "score"};
@@ -3115,7 +3616,7 @@ static void emit_semantic_results(yyjson_mut_doc *doc, yyjson_mut_val *root,
     }
     yyjson_mut_obj_add_val(doc, sem, "cols", scols);
     yyjson_mut_val *sem_results = yyjson_mut_arr(doc);
-    for (int v = 0; v < vcount; v++) {
+    for (int v = 0; v < returned; v++) {
         yyjson_mut_val *vitem = yyjson_mut_arr(doc);
         yyjson_mut_arr_add_strcpy(doc, vitem, vresults[v].qualified_name);
         yyjson_mut_arr_add_strcpy(doc, vitem, vresults[v].label);
@@ -3132,8 +3633,8 @@ static void emit_semantic_results(yyjson_mut_doc *doc, yyjson_mut_val *root,
  * Returns true if semantic_query was provided as a non-array (type error —
  * caller should surface to the user). */
 static bool run_semantic_query_core(const char *args, cbm_store_t *store, const char *project,
-                                    int limit, cbm_vector_result_t **out_vresults, int *out_vcount,
-                                    bool *out_present) {
+                                    int materialize_limit, cbm_vector_result_t **out_vresults,
+                                    int *out_vcount, bool *out_present) {
     enum { MAX_KW_SEARCH = 32 };
     *out_vresults = NULL;
     *out_vcount = 0;
@@ -3154,9 +3655,8 @@ static bool run_semantic_query_core(const char *args, cbm_store_t *store, const
         int ki = extract_semantic_keywords(sq_val, keywords, MAX_KW_SEARCH);
         cbm_vector_result_t *vresults = NULL;
         int vcount = 0;
-        int sem_limit = limit > 0 ? limit : CBM_SZ_16;
-        if (cbm_store_vector_search(store, project, keywords, ki, sem_limit, &vresults, &vcount) ==
-                CBM_STORE_OK &&
+        if (cbm_store_vector_search(store, project, keywords, ki, materialize_limit, &vresults,
+                                    &vcount) == CBM_STORE_OK &&
             vcount > 0) {
             *out_vresults = vresults;
             *out_vcount = vcount;
@@ -3168,26 +3668,20 @@ static bool run_semantic_query_core(const char *args, cbm_store_t *store, const
     return type_error;
 }
 
-/* Append the semantic_query vector-search results onto the doc.  Returns
- * true if semantic_query was provided as a non-array (type error — caller
- * should surface to the user). */
-static bool run_semantic_query(yyjson_mut_doc *doc, yyjson_mut_val *root, const char *args,
-                               cbm_store_t *store, const char *project, int limit) {
-    cbm_vector_result_t *vresults = NULL;
-    int vcount = 0;
-    bool type_error =
-        run_semantic_query_core(args, store, project, limit, &vresults, &vcount, NULL);
-    if (vcount > 0) {
-        emit_semantic_results(doc, root, vresults, vcount);
-        cbm_store_free_vector_results(vresults, vcount);
+static bool search_graph_arg_present(const char *args, const char *name) {
+    yyjson_doc *doc = yyjson_read(args, strlen(args), 0);
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    bool present = root && yyjson_is_obj(root) && yyjson_obj_get(root, name) != NULL;
+    if (doc) {
+        yyjson_doc_free(doc);
     }
-    return type_error;
+    return present;
 }
 
 /* ── Tree output for search_graph ───────────────────────────────────
- * Default response encoding: grouped tree rows (compact_out.h). The same
- * model is available as structured JSON via format:"json"; include_connected
- * adds a `connected` column in BOTH encodings. */
+ * Default response encoding chooses the smaller complete direct/grouped tree
+ * (compact_out.h). format:"json" keeps a stable grouped model;
+ * include_connected adds a `connected` column in both encodings. */
 
 enum { SG_MAX_EXTRA_FIELDS = 12 };
 
@@ -3255,31 +3749,6 @@ static int sg_parse_fields(const char *args, const char *out[], int max_out, yyj
     return n;
 }
 
-/* Append one row's extra-field cells, pulled from the node's properties. */
-static void sg_toon_extra_cells(cbm_sb_t *sb, const char *props_json, const char *const *fields,
-                                int nfields) {
-    yyjson_doc *pd =
-        (props_json && props_json[0]) ? yyjson_read(props_json, strlen(props_json), 0) : NULL;
-    yyjson_val *pr = pd ? yyjson_doc_get_root(pd) : NULL;
-    for (int f = 0; f < nfields; f++) {
-        yyjson_val *v = (pr && yyjson_is_obj(pr)) ? yyjson_obj_get(pr, fields[f]) : NULL;
-        if (v && yyjson_is_str(v)) {
-            cbm_tree_cell_str(sb, yyjson_get_str(v), false);
-        } else if (v && yyjson_is_bool(v)) {
-            cbm_tree_cell_bool(sb, yyjson_get_bool(v), false);
-        } else if (v && yyjson_is_int(v)) {
-            cbm_tree_cell_int(sb, yyjson_get_int(v), false);
-        } else if (v && yyjson_is_real(v)) {
-            cbm_tree_cell_real(sb, yyjson_get_real(v), false);
-        } else {
-            cbm_tree_cell_str(sb, "", false);
-        }
-    }
-    if (pd) {
-        yyjson_doc_free(pd);
-    }
-}
-
 /* "start-end" line range, or empty when the node carries no line info. */
 static void sg_lines_str(char *out, size_t sz, int start, int end) {
     if (start > 0) {
@@ -3289,51 +3758,11 @@ static void sg_lines_str(char *out, size_t sz, int start, int end) {
     }
 }
 
-/* Emit the regex-path search results as a TOON table. */
-static void emit_search_results_toon(cbm_sb_t *sb, const cbm_search_output_t *out, int offset,
-                                     const char *const *fields, int nfields, bool detail_ids) {
-    cbm_tree_scalar_int(sb, "total", out->total);
-    if (detail_ids) {
-        /* ids tier: bare qn enumeration — for "list everything matching X"
-         * sweeps where per-row metadata is noise (LocAgent's fold tier). */
-        static const char *const id_cols[] = {"qn"};
-        cbm_tree_table_header(sb, "results", out->count, id_cols, 1);
-        for (int i = 0; i < out->count; i++) {
-            cbm_tree_row_begin(sb);
-            cbm_tree_cell_str(sb, out->results[i].node.qualified_name, true);
-            cbm_tree_row_end(sb);
-        }
-        cbm_tree_scalar_bool(sb, "has_more", out->total > offset + out->count);
-        return;
-    }
-    const char *cols[6 + SG_MAX_EXTRA_FIELDS] = {"qn", "label", "file", "lines", "in", "out"};
-    int ncols = 6;
-    for (int f = 0; f < nfields; f++) {
-        cols[ncols++] = fields[f];
-    }
-    cbm_tree_table_header(sb, "results", out->count, cols, ncols);
-    for (int i = 0; i < out->count; i++) {
-        const cbm_search_result_t *sr = &out->results[i];
-        char lines[CBM_SZ_32];
-        sg_lines_str(lines, sizeof(lines), sr->node.start_line, sr->node.end_line);
-        cbm_tree_row_begin(sb);
-        cbm_tree_cell_str(sb, sr->node.qualified_name, true);
-        cbm_tree_cell_str(sb, sr->node.label, false);
-        cbm_tree_cell_str(sb, sr->node.file_path, false);
-        cbm_tree_cell_str(sb, lines, false);
-        cbm_tree_cell_int(sb, sr->in_degree, false);
-        cbm_tree_cell_int(sb, sr->out_degree, false);
-        sg_toon_extra_cells(sb, sr->node.properties_json, fields, nfields);
-        cbm_tree_row_end(sb);
-    }
-    cbm_tree_scalar_bool(sb, "has_more", out->total > offset + out->count);
-}
-
 /* ── Tree format (Phase-2 A/B candidate) ────────────────────────────
  * Prefix-factored, file-grouped output: the shared (qn-prefix, file) pair is
  * printed ONCE per group, rows beneath carry only the short name + data
- * cells. The reconstruction rule (qn = group-prefix + "." + name) is stated
- * once in the header so agents can copy exact join keys into follow-up
+ * cells. The reconstruction rule accounts for dotless qualified names and is
+ * stated once in the header so agents can copy exact join keys into follow-up
  * calls. Research basis: HDT front-coding (prefix factoring), LocAgent tree
  * ablation (tree > flat/DOT for LLM comprehension), Lost-in-Distance
  * (related rows adjacent — grouping by module does exactly that). */
@@ -3344,55 +3773,293 @@ static size_t sg_qn_prefix_len(const char *qn) {
     return last ? (size_t)(last - qn) : 0;
 }
 
-static int sg_cmp_by_qn(const void *pa, const void *pb) {
-    const cbm_search_result_t *a = (const cbm_search_result_t *)pa;
-    const cbm_search_result_t *b = (const cbm_search_result_t *)pb;
-    const char *qa = a->node.qualified_name ? a->node.qualified_name : "";
-    const char *qb = b->node.qualified_name ? b->node.qualified_name : "";
-    return strcmp(qa, qb);
+typedef struct {
+    int returned;
+    int fields_returned;
+    int semantic_returned;
+    bool connected_returned;
+    bool core_hint_returned;
+    bool budget_hit;
+    bool floor_exceeded;
+} sg_render_plan_t;
+
+typedef struct {
+    const cbm_vector_result_t *results;
+    int total;
+    int offset;
+    int limit;
+    bool total_exact;
+    bool present;
+} sg_semantic_page_t;
+
+static bool sg_page_has_more(int total, int offset, int returned) {
+    return (long long)total > (long long)offset + returned;
+}
+
+static void sg_emit_paging_tree(cbm_sb_t *sb, int total, int offset, const sg_render_plan_t *plan,
+                                int requested_fields, bool connected_requested,
+                                size_t max_output_bytes, bool continuation_supported,
+                                bool continuation_requires_positive_limit) {
+    bool rows_remain = sg_page_has_more(total, offset, plan->returned);
+    bool has_more = continuation_supported && rows_remain;
+    bool engine_saturated = !continuation_supported && rows_remain;
+    cbm_tree_scalar_int(sb, "total", total);
+    cbm_tree_scalar_int(sb, "returned", plan->returned);
+    cbm_tree_scalar_bool(sb, "has_more", has_more);
+    if (has_more && plan->returned > 0) {
+        cbm_tree_scalar_int(sb, "next_offset", offset + plan->returned);
+    } else if (has_more) {
+        cbm_tree_scalar_bool(sb,
+                             continuation_requires_positive_limit
+                                 ? "continuation_requires_positive_limit"
+                                 : "continuation_requires_higher_budget",
+                             true);
+    }
+    bool truncated = rows_remain || plan->budget_hit;
+    cbm_tree_scalar_bool(sb, "truncated", truncated);
+    if (truncated) {
+        cbm_tree_scalar_str(sb, "truncation_reason",
+                            plan->budget_hit   ? "output_budget"
+                            : engine_saturated ? "engine_limit"
+                                               : "page_limit");
+    }
+    if (plan->budget_hit) {
+        cbm_tree_scalar_int(sb, "max_output_bytes", (long long)max_output_bytes);
+    }
+    if (requested_fields > plan->fields_returned) {
+        cbm_tree_scalar_int(sb, "fields_omitted", requested_fields - plan->fields_returned);
+    }
+    if (connected_requested && !plan->connected_returned) {
+        cbm_tree_scalar_bool(sb, "connected_omitted", true);
+    }
+    if (plan->floor_exceeded) {
+        cbm_tree_scalar_bool(sb, "output_budget_floor_exceeded", true);
+        cbm_tree_scalar_str(sb, "hint",
+                            "first identity row exceeds max_output_bytes; raise "
+                            "max_output_tokens");
+    }
+}
+
+static void sg_emit_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int total, int offset,
+                                const sg_render_plan_t *plan, int requested_fields,
+                                bool connected_requested, size_t max_output_bytes,
+                                bool continuation_supported,
+                                bool continuation_requires_positive_limit) {
+    bool rows_remain = sg_page_has_more(total, offset, plan->returned);
+    bool has_more = continuation_supported && rows_remain;
+    bool engine_saturated = !continuation_supported && rows_remain;
+    yyjson_mut_obj_add_int(doc, root, "total", total);
+    yyjson_mut_obj_add_int(doc, root, "returned", plan->returned);
+    yyjson_mut_obj_add_int(doc, root, "count", plan->returned);
+    yyjson_mut_obj_add_bool(doc, root, "has_more", has_more);
+    if (has_more && plan->returned > 0) {
+        yyjson_mut_obj_add_int(doc, root, "next_offset", offset + plan->returned);
+    } else if (has_more) {
+        yyjson_mut_obj_add_bool(doc, root,
+                                continuation_requires_positive_limit
+                                    ? "continuation_requires_positive_limit"
+                                    : "continuation_requires_higher_budget",
+                                true);
+    }
+    bool truncated = rows_remain || plan->budget_hit;
+    yyjson_mut_obj_add_bool(doc, root, "truncated", truncated);
+    if (truncated) {
+        yyjson_mut_obj_add_str(doc, root, "truncation_reason",
+                               plan->budget_hit   ? "output_budget"
+                               : engine_saturated ? "engine_limit"
+                                                  : "page_limit");
+    }
+    if (plan->budget_hit) {
+        yyjson_mut_obj_add_uint(doc, root, "max_output_bytes", max_output_bytes);
+    }
+    if (requested_fields > plan->fields_returned) {
+        yyjson_mut_obj_add_int(doc, root, "fields_omitted",
+                               requested_fields - plan->fields_returned);
+    }
+    if (connected_requested && !plan->connected_returned) {
+        yyjson_mut_obj_add_bool(doc, root, "connected_omitted", true);
+    }
+    if (plan->floor_exceeded) {
+        yyjson_mut_obj_add_bool(doc, root, "output_budget_floor_exceeded", true);
+        yyjson_mut_obj_add_str(doc, root, "hint",
+                               "first identity row exceeds max_output_bytes; raise "
+                               "max_output_tokens");
+    }
+}
+
+static bool sg_semantic_has_remaining_rows(const sg_semantic_page_t *semantic, int returned) {
+    return semantic && sg_page_has_more(semantic->total, semantic->offset, returned);
+}
+
+/* semantic_offset is deliberately bounded: vector ranking certifies an
+ * ordered prefix, so an unbounded offset would turn one tiny MCP request into
+ * unbounded materialization. A continuation is usable only when the next
+ * offset is accepted by the public schema/runtime. */
+static bool sg_semantic_engine_saturated(const sg_semantic_page_t *semantic, int returned) {
+    return sg_semantic_has_remaining_rows(semantic, returned) && returned > 0 &&
+           (long long)semantic->offset + returned > MCP_QUERY_MAX_VISIBLE_ROWS;
+}
+
+static bool sg_semantic_has_more(const sg_semantic_page_t *semantic, int returned) {
+    return sg_semantic_has_remaining_rows(semantic, returned) &&
+           !sg_semantic_engine_saturated(semantic, returned);
+}
+
+static void sg_emit_semantic_paging_tree(cbm_sb_t *sb, const sg_semantic_page_t *semantic,
+                                         int returned) {
+    bool saturated = sg_semantic_engine_saturated(semantic, returned);
+    bool has_more = sg_semantic_has_more(semantic, returned);
+    cbm_tree_scalar_int(sb, "semantic_total", semantic->total);
+    cbm_tree_scalar_str(sb, "semantic_total_relation",
+                        semantic->total_exact && !saturated ? "eq" : "gte");
+    cbm_tree_scalar_int(sb, "semantic_returned", returned);
+    cbm_tree_scalar_bool(sb, "semantic_has_more", has_more);
+    if (has_more && returned > 0) {
+        cbm_tree_scalar_int(sb, "semantic_next_offset", semantic->offset + returned);
+    } else if (has_more) {
+        cbm_tree_scalar_bool(sb,
+                             semantic->limit == 0 ? "semantic_continuation_requires_positive_limit"
+                                                  : "semantic_continuation_requires_higher_budget",
+                             true);
+    }
+    if (saturated) {
+        cbm_tree_scalar_bool(sb, "semantic_engine_saturated", true);
+        cbm_tree_scalar_bool(sb, "semantic_continuation_unavailable", true);
+    }
+}
+
+static void sg_emit_semantic_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *root,
+                                         const sg_semantic_page_t *semantic, int returned) {
+    bool saturated = sg_semantic_engine_saturated(semantic, returned);
+    bool has_more = sg_semantic_has_more(semantic, returned);
+    yyjson_mut_obj_add_int(doc, root, "semantic_total", semantic->total);
+    yyjson_mut_obj_add_str(doc, root, "semantic_total_relation",
+                           semantic->total_exact && !saturated ? "eq" : "gte");
+    yyjson_mut_obj_add_int(doc, root, "semantic_returned", returned);
+    yyjson_mut_obj_add_bool(doc, root, "semantic_has_more", has_more);
+    if (has_more && returned > 0) {
+        yyjson_mut_obj_add_int(doc, root, "semantic_next_offset", semantic->offset + returned);
+    } else if (has_more) {
+        yyjson_mut_obj_add_bool(doc, root,
+                                semantic->limit == 0
+                                    ? "semantic_continuation_requires_positive_limit"
+                                    : "semantic_continuation_requires_higher_budget",
+                                true);
+    }
+    if (saturated) {
+        yyjson_mut_obj_add_bool(doc, root, "semantic_engine_saturated", true);
+        yyjson_mut_obj_add_bool(doc, root, "semantic_continuation_unavailable", true);
+    }
+}
+
+#ifdef CBM_ENABLE_TEST_SEAMS
+char *cbm_mcp_render_semantic_paging_for_testing(int total, int offset, int returned, int limit,
+                                                 bool total_exact, bool json_format) {
+    sg_semantic_page_t semantic = {
+        .total = total,
+        .offset = offset,
+        .limit = limit,
+        .total_exact = total_exact,
+        .present = true,
+    };
+    if (!json_format) {
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        sg_emit_semantic_paging_tree(&sb, &semantic, returned);
+        sg_render_plan_t plan = {.returned = returned, .semantic_returned = returned};
+        sg_emit_paging_tree(&sb, total, offset, &plan, 0, false, SIZE_MAX,
+                            !sg_semantic_engine_saturated(&semantic, returned), false);
+        return cbm_sb_finish(&sb);
+    }
+
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *root = yyjson_mut_obj(doc);
+    yyjson_mut_doc_set_root(doc, root);
+    sg_emit_semantic_paging_json(doc, root, &semantic, returned);
+    sg_render_plan_t plan = {.returned = returned, .semantic_returned = returned};
+    sg_emit_paging_json(doc, root, total, offset, &plan, 0, false, SIZE_MAX,
+                        !sg_semantic_engine_saturated(&semantic, returned), false);
+    char *json = yy_doc_to_str(doc);
+    yyjson_mut_doc_free(doc);
+    return json;
 }
+#endif
 
-static void emit_search_results_tree(cbm_sb_t *sb, cbm_search_output_t *out, int offset,
-                                     const char *const *fields, int nfields, cbm_store_t *store,
-                                     const char *relationship, bool include_connected) {
-    char buf[CBM_SZ_512];
-    char extra_cols[CBM_SZ_256] = "";
+static void emit_search_results_ids_tree(cbm_sb_t *sb, const cbm_search_output_t *out,
+                                         int returned) {
+    static const char *const id_cols[] = {"qn"};
+    cbm_tree_table_header(sb, "results", returned, id_cols, 1);
+    for (int i = 0; i < returned; i++) {
+        cbm_tree_row_begin(sb);
+        cbm_tree_cell_str(sb, out->results[i].node.qualified_name, true);
+        cbm_tree_row_end(sb);
+    }
+}
+
+static void emit_search_results_ids_json(yyjson_mut_doc *doc, yyjson_mut_val *root,
+                                         const cbm_search_output_t *out, int returned) {
+    yyjson_mut_val *cols = yyjson_mut_arr(doc);
+    yyjson_mut_arr_add_str(doc, cols, "qn");
+    yyjson_mut_obj_add_val(doc, root, "cols", cols);
+    yyjson_mut_val *rows = yyjson_mut_arr(doc);
+    for (int i = 0; i < returned; i++) {
+        yyjson_mut_val *row = yyjson_mut_arr(doc);
+        yyjson_mut_arr_add_strcpy(
+            doc, row,
+            out->results[i].node.qualified_name ? out->results[i].node.qualified_name : "");
+        yyjson_mut_arr_add_val(rows, row);
+    }
+    yyjson_mut_obj_add_val(doc, root, "rows", rows);
+}
+
+static void emit_search_results_grouped_tree(cbm_sb_t *sb, const cbm_search_output_t *out,
+                                             const char *const *fields, int nfields,
+                                             cbm_store_t *store, const char *relationship,
+                                             bool include_connected, int returned) {
+    cbm_sb_append(sb, "results: ");
+    char count_buf[CBM_SZ_32];
+    snprintf(count_buf, sizeof(count_buf), "%d", returned);
+    cbm_sb_append(sb, count_buf);
+    cbm_sb_append(sb, "  (rows: name label lines in out");
     for (int f = 0; f < nfields; f++) {
-        strncat(extra_cols, " ", sizeof(extra_cols) - strlen(extra_cols) - 1);
-        strncat(extra_cols, fields[f], sizeof(extra_cols) - strlen(extra_cols) - 1);
+        cbm_sb_append(sb, " ");
+        cbm_sb_append(sb, fields[f]);
     }
     if (include_connected) {
-        strncat(extra_cols, " connected", sizeof(extra_cols) - strlen(extra_cols) - 1);
+        cbm_sb_append(sb, " connected");
     }
-    snprintf(buf, sizeof(buf),
-             "total: %d\nresults: %d  (rows: name label lines in out%s; "
-             "qn = group prefix + \".\" + name)\n",
-             out->total, out->count, extra_cols);
-    cbm_sb_append(sb, buf);
-    /* Sort by qn so same-prefix rows are adjacent (module clustering). */
-    if (out->count > 1) {
-        qsort(out->results, (size_t)out->count, sizeof(cbm_search_result_t), sg_cmp_by_qn);
-    }
-    char cur_group[CBM_SZ_1K] = "";
-    for (int i = 0; i < out->count; i++) {
+    cbm_sb_append(sb, "; group prefix \"-\" means empty; "
+                      "qn = prefix empty ? name : prefix + \".\" + name)\n");
+
+    char *previous_prefix = NULL;
+    char *previous_file = NULL;
+    for (int i = 0; i < returned; i++) {
         const cbm_search_result_t *sr = &out->results[i];
         const char *qn = sr->node.qualified_name ? sr->node.qualified_name : "";
         const char *file = sr->node.file_path ? sr->node.file_path : "";
         size_t plen = sg_qn_prefix_len(qn);
-        char group[CBM_SZ_1K];
-        snprintf(group, sizeof(group), "%.*s (%s)", (int)plen, qn, file);
-        if (strcmp(group, cur_group) != 0) {
-            snprintf(cur_group, sizeof(cur_group), "%s", group);
-            cbm_sb_append(sb, group);
-            cbm_sb_append(sb, ":\n");
+        bool same_group = previous_prefix && strlen(previous_prefix) == plen &&
+                          memcmp(previous_prefix, qn, plen) == 0 && previous_file &&
+                          strcmp(previous_file, file) == 0;
+        if (!same_group) {
+            free(previous_prefix);
+            free(previous_file);
+            previous_prefix = cbm_strndup(qn, plen);
+            previous_file = heap_strdup(file);
+            cbm_tree_cell_str(sb, previous_prefix ? previous_prefix : "", true);
+            cbm_sb_append(sb, " (");
+            cbm_tree_cell_str(sb, previous_file ? previous_file : "", true);
+            cbm_sb_append(sb, "):\n");
         }
         const char *shortname = plen ? qn + plen + 1 : qn;
         char lines[CBM_SZ_32];
         sg_lines_str(lines, sizeof(lines), sr->node.start_line, sr->node.end_line);
-        char row[CBM_SZ_1K];
-        snprintf(row, sizeof(row), "  %s %s %s %d %d", shortname,
-                 sr->node.label ? sr->node.label : "", lines, sr->in_degree, sr->out_degree);
-        cbm_sb_append(sb, row);
+        cbm_sb_append(sb, "  ");
+        cbm_tree_cell_str(sb, shortname, true);
+        cbm_tree_cell_str(sb, sr->node.label ? sr->node.label : "", false);
+        cbm_tree_cell_str(sb, lines, false);
+        cbm_tree_cell_int(sb, sr->in_degree, false);
+        cbm_tree_cell_int(sb, sr->out_degree, false);
         /* Extra property columns (fields param). Routed through the shared
          * cell emitters so values with spaces (signatures, docstrings) are
          * QUOTED — a raw append would shift every following column. Missing
@@ -3422,15 +4089,87 @@ static void emit_search_results_tree(cbm_sb_t *sb, cbm_search_output_t *out, int
             }
         }
         if (include_connected && sr->node.id > 0) {
-            char joined[CBM_SZ_1K];
-            enrich_connected_joined(store, sr->node.id, relationship, joined, sizeof(joined));
-            cbm_tree_cell_str(sb, joined, false); /* empty emits "-" */
+            char *joined = enrich_connected_joined(store, sr->node.id, relationship);
+            cbm_tree_cell_str(sb, joined ? joined : "", false); /* empty emits "-" */
+            free(joined);
         }
         cbm_sb_append(sb, "\n");
     }
-    snprintf(buf, sizeof(buf), "has_more: %s\n",
-             out->total > offset + out->count ? "true" : "false");
-    cbm_sb_append(sb, buf);
+    free(previous_prefix);
+    free(previous_file);
+}
+
+/* The grouped search shape is excellent when rows share a module/file, but its
+ * reconstruction rule and group headers are pure overhead for a singleton or
+ * a scatter of unrelated rows. The common, no-extra-fields path can be
+ * represented as a regular table, so render both byte-for-byte and keep the
+ * smaller lossless form. Extra property/connected columns retain the grouped
+ * emitter because their cells are dynamically typed. */
+static char *render_search_results_flat_tree(const cbm_search_output_t *out, int returned) {
+    static const char *const cols[] = {"qn", "label", "file", "lines", "in", "out"};
+    static const bool string_cols[] = {true, true, true, true, false, false};
+    static const bool prefix_cols[] = {true, false, true, false, false, false};
+    enum { COLS = 6, CELL_TEXTS = 3 };
+    if (returned == 0) {
+        cbm_sb_t empty;
+        cbm_sb_init(&empty);
+        cbm_tree_table_header(&empty, "results", 0, cols, COLS);
+        return cbm_sb_finish(&empty);
+    }
+    if (returned < 0 || (size_t)returned > (size_t)-1 / (COLS * sizeof(char *)) ||
+        (size_t)returned > (size_t)-1 / (CELL_TEXTS * CBM_SZ_32)) {
+        return NULL;
+    }
+    const char **cells = calloc((size_t)returned * COLS, sizeof(*cells));
+    char *text = calloc((size_t)returned * CELL_TEXTS, CBM_SZ_32);
+    if (!cells || !text) {
+        free(cells);
+        free(text);
+        return NULL;
+    }
+    for (int i = 0; i < returned; i++) {
+        const cbm_search_result_t *sr = &out->results[i];
+        char *lines = text + (size_t)(i * CELL_TEXTS) * CBM_SZ_32;
+        char *in_degree = lines + CBM_SZ_32;
+        char *out_degree = in_degree + CBM_SZ_32;
+        sg_lines_str(lines, CBM_SZ_32, sr->node.start_line, sr->node.end_line);
+        snprintf(in_degree, CBM_SZ_32, "%d", sr->in_degree);
+        snprintf(out_degree, CBM_SZ_32, "%d", sr->out_degree);
+        cells[(size_t)i * COLS] = sr->node.qualified_name ? sr->node.qualified_name : "";
+        cells[(size_t)i * COLS + 1U] = sr->node.label ? sr->node.label : "";
+        cells[(size_t)i * COLS + 2U] = sr->node.file_path ? sr->node.file_path : "";
+        cells[(size_t)i * COLS + 3U] = lines;
+        cells[(size_t)i * COLS + 4U] = in_degree;
+        cells[(size_t)i * COLS + 5U] = out_degree;
+    }
+    cbm_sb_t flat;
+    cbm_sb_init(&flat);
+    cbm_tree_table_rows_profiled(&flat, "results", returned, cols, COLS, cells, string_cols,
+                                 prefix_cols);
+    char *rendered = cbm_sb_finish(&flat);
+    free(cells);
+    free(text);
+    return rendered;
+}
+
+static void emit_search_results_tree(cbm_sb_t *sb, const cbm_search_output_t *out,
+                                     const char *const *fields, int nfields, cbm_store_t *store,
+                                     const char *relationship, bool include_connected,
+                                     int returned) {
+    cbm_sb_t grouped;
+    cbm_sb_init(&grouped);
+    emit_search_results_grouped_tree(&grouped, out, fields, nfields, store, relationship,
+                                     include_connected, returned);
+    char *grouped_text = cbm_sb_finish(&grouped);
+    char *flat_text =
+        nfields == 0 && !include_connected ? render_search_results_flat_tree(out, returned) : NULL;
+    if (flat_text && (!grouped_text || strlen(flat_text) < strlen(grouped_text))) {
+        cbm_sb_append(sb, flat_text);
+    } else if (grouped_text) {
+        cbm_sb_append(sb, grouped_text);
+    }
+    free(flat_text);
+    free(grouped_text);
 }
 
 /* json-stringified tree: the SAME grouped model as the text tree, serialized
@@ -3438,12 +4177,11 @@ static void emit_search_results_tree(cbm_sb_t *sb, cbm_search_output_t *out, int
  * (qn_prefix, file) and column-ordered row ARRAYS (never per-row key
  * envelopes; that legacy shape was 84% key overhead). */
 static void emit_search_results_tree_json(yyjson_mut_doc *doc, yyjson_mut_val *root,
-                                          cbm_search_output_t *out, int offset,
-                                          const char *const *fields, int nfields,
-                                          cbm_store_t *store, const char *relationship,
-                                          bool include_connected) {
-    yyjson_mut_obj_add_int(doc, root, "total", out->total);
-    yyjson_mut_obj_add_int(doc, root, "count", out->count);
+                                          const cbm_search_output_t *out, const char *const *fields,
+                                          int nfields, cbm_store_t *store, const char *relationship,
+                                          bool include_connected, int returned) {
+    yyjson_mut_obj_add_str(doc, root, "qn_rule",
+                           "qn = qn_prefix == \"\" ? name : qn_prefix + \".\" + name");
     yyjson_mut_val *cols = yyjson_mut_arr(doc);
     static const char *const col_names[] = {"name", "label", "lines", "in", "out"};
     for (size_t i = 0; i < sizeof(col_names) / sizeof(col_names[0]); i++) {
@@ -3456,26 +4194,26 @@ static void emit_search_results_tree_json(yyjson_mut_doc *doc, yyjson_mut_val *r
         yyjson_mut_arr_add_str(doc, cols, "connected");
     }
     yyjson_mut_obj_add_val(doc, root, "cols", cols);
-    if (out->count > 1) {
-        qsort(out->results, (size_t)out->count, sizeof(cbm_search_result_t), sg_cmp_by_qn);
-    }
     yyjson_mut_val *groups = yyjson_mut_arr(doc);
     yyjson_mut_val *cur = NULL;
     yyjson_mut_val *cur_rows = NULL;
-    char cur_key[CBM_SZ_1K] = "";
-    for (int i = 0; i < out->count; i++) {
+    char *previous_prefix = NULL;
+    char *previous_file = NULL;
+    for (int i = 0; i < returned; i++) {
         const cbm_search_result_t *sr = &out->results[i];
         const char *qn = sr->node.qualified_name ? sr->node.qualified_name : "";
         const char *file = sr->node.file_path ? sr->node.file_path : "";
         size_t plen = sg_qn_prefix_len(qn);
-        char key[CBM_SZ_1K];
-        snprintf(key, sizeof(key), "%.*s|%s", (int)plen, qn, file);
-        if (!cur || strcmp(key, cur_key) != 0) {
-            snprintf(cur_key, sizeof(cur_key), "%s", key);
+        bool same_group = previous_prefix && strlen(previous_prefix) == plen &&
+                          memcmp(previous_prefix, qn, plen) == 0 && previous_file &&
+                          strcmp(previous_file, file) == 0;
+        if (!same_group) {
+            free(previous_prefix);
+            free(previous_file);
+            previous_prefix = cbm_strndup(qn, plen);
+            previous_file = heap_strdup(file);
             cur = yyjson_mut_obj(doc);
-            char prefix[CBM_SZ_1K];
-            snprintf(prefix, sizeof(prefix), "%.*s", (int)plen, qn);
-            yyjson_mut_obj_add_strcpy(doc, cur, "qn_prefix", prefix);
+            yyjson_mut_obj_add_strncpy(doc, cur, "qn_prefix", qn, plen);
             yyjson_mut_obj_add_strcpy(doc, cur, "file", file);
             cur_rows = yyjson_mut_arr(doc);
             yyjson_mut_obj_add_val(doc, cur, "rows", cur_rows);
@@ -3518,16 +4256,17 @@ static void emit_search_results_tree_json(yyjson_mut_doc *doc, yyjson_mut_val *r
         }
         yyjson_mut_arr_add_val(cur_rows, row);
     }
+    free(previous_prefix);
+    free(previous_file);
     yyjson_mut_obj_add_val(doc, root, "groups", groups);
-    yyjson_mut_obj_add_bool(doc, root, "has_more", out->total > offset + out->count);
 }
 
 /* Emit semantic vector-search results as a TOON table. */
 static void emit_semantic_results_toon(cbm_sb_t *sb, const cbm_vector_result_t *vresults,
-                                       int vcount) {
+                                       int returned) {
     static const char *const cols[] = {"qn", "label", "file", "score"};
-    cbm_tree_table_header(sb, "semantic", vcount, cols, 4);
-    for (int v = 0; v < vcount; v++) {
+    cbm_tree_table_header(sb, "semantic", returned, cols, 4);
+    for (int v = 0; v < returned; v++) {
         cbm_tree_row_begin(sb);
         cbm_tree_cell_str(sb, vresults[v].qualified_name, true);
         cbm_tree_cell_str(sb, vresults[v].label, false);
@@ -3537,6 +4276,108 @@ static void emit_semantic_results_toon(cbm_sb_t *sb, const cbm_vector_result_t *
     }
 }
 
+static char *sg_render_payload(bool json_format, const cbm_search_output_t *out, int offset,
+                               const char *const *fields, int requested_fields, cbm_store_t *store,
+                               const char *relationship, bool connected_requested, bool detail_ids,
+                               const sg_semantic_page_t *semantic, bool semantic_only,
+                               const char *diagnostic_hint, const sg_render_plan_t *plan,
+                               size_t max_output_bytes) {
+    sg_render_plan_t meta_plan = *plan;
+    int page_total = semantic_only ? semantic->total : out->total;
+    int page_offset = semantic_only ? semantic->offset : offset;
+    if (semantic_only) {
+        meta_plan.returned = plan->semantic_returned;
+    }
+    bool continuation_supported =
+        !semantic_only || !sg_semantic_engine_saturated(semantic, plan->semantic_returned);
+
+    if (!json_format) {
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        if (!semantic_only) {
+            if (detail_ids) {
+                emit_search_results_ids_tree(&sb, out, plan->returned);
+            } else {
+                emit_search_results_tree(&sb, out, fields, plan->fields_returned, store,
+                                         relationship, plan->connected_returned, plan->returned);
+            }
+        }
+        if (semantic->present) {
+            sg_emit_semantic_paging_tree(&sb, semantic, plan->semantic_returned);
+            emit_semantic_results_toon(&sb, semantic->results, plan->semantic_returned);
+        }
+        if (plan->core_hint_returned && diagnostic_hint) {
+            cbm_tree_scalar_str(&sb, "hint", diagnostic_hint);
+        }
+        sg_emit_paging_tree(&sb, page_total, page_offset, &meta_plan, requested_fields,
+                            connected_requested, max_output_bytes, continuation_supported,
+                            semantic_only && semantic->limit == 0);
+        return cbm_sb_finish(&sb);
+    }
+
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *root = yyjson_mut_obj(doc);
+    yyjson_mut_doc_set_root(doc, root);
+    if (!semantic_only) {
+        if (detail_ids) {
+            emit_search_results_ids_json(doc, root, out, plan->returned);
+        } else {
+            emit_search_results_tree_json(doc, root, out, fields, plan->fields_returned, store,
+                                          relationship, plan->connected_returned, plan->returned);
+        }
+    }
+    if (semantic->present) {
+        sg_emit_semantic_paging_json(doc, root, semantic, plan->semantic_returned);
+        emit_semantic_results(doc, root, semantic->results, plan->semantic_returned);
+    }
+    if (plan->core_hint_returned && diagnostic_hint) {
+        yyjson_mut_obj_add_strcpy(doc, root, "hint", diagnostic_hint);
+    }
+    sg_emit_paging_json(doc, root, page_total, page_offset, &meta_plan, requested_fields,
+                        connected_requested, max_output_bytes, continuation_supported,
+                        semantic_only && semantic->limit == 0);
+    char *json = yy_doc_to_str(doc);
+    yyjson_mut_doc_free(doc);
+    return json;
+}
+
+static char *sg_budget_floor(bool json_format, int total, int offset,
+                             const sg_semantic_page_t *semantic, size_t max_output_bytes,
+                             bool semantic_only) {
+    sg_render_plan_t floor = {
+        .returned = 0,
+        .fields_returned = 0,
+        .semantic_returned = 0,
+        .connected_returned = false,
+        .core_hint_returned = false,
+        .budget_hit = true,
+        .floor_exceeded = true,
+    };
+    int page_total = semantic_only ? semantic->total : total;
+    int page_offset = semantic_only ? semantic->offset : offset;
+    if (!json_format) {
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        if (semantic->present) {
+            sg_emit_semantic_paging_tree(&sb, semantic, 0);
+        }
+        sg_emit_paging_tree(&sb, page_total, page_offset, &floor, 0, false, max_output_bytes, true,
+                            semantic_only && semantic->limit == 0);
+        return cbm_sb_finish(&sb);
+    }
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *root = yyjson_mut_obj(doc);
+    yyjson_mut_doc_set_root(doc, root);
+    if (semantic->present) {
+        sg_emit_semantic_paging_json(doc, root, semantic, 0);
+    }
+    sg_emit_paging_json(doc, root, page_total, page_offset, &floor, 0, false, max_output_bytes,
+                        true, semantic_only && semantic->limit == 0);
+    char *json = yy_doc_to_str(doc);
+    yyjson_mut_doc_free(doc);
+    return json;
+}
+
 static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     /* Inner phase split: every tool leaks the same ~4 MB per request, so the
      * retainer is in what the handlers share -- store resolution or the query
@@ -3554,23 +4395,68 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
         return not_indexed;
     }
 
-    /* Response encoding: grouped tree rows by default; format:"json" emits
-     * the SAME tree model as structured JSON (groups + row arrays). */
+    /* Response encoding: the default tree chooses direct/grouped by serialized
+     * size; format:"json" keeps the stable grouped model. The token argument
+     * becomes a deterministic byte ceiling: tokenizers differ, bytes do not. */
     char *format_arg = cbm_mcp_get_string_arg(args, "format");
-    bool legacy_json = format_arg && strcmp(format_arg, "json") == 0;
+    bool json_format = format_arg && strcmp(format_arg, "json") == 0;
     free(format_arg);
+    int limit = cbm_mcp_get_int_arg(args, "limit", CBM_DEFAULT_SEARCH_LIMIT);
+    if (limit < 1) {
+        limit = 1;
+    } else if (limit > 500) {
+        limit = 500;
+    }
+    int offset = cbm_mcp_get_int_arg(args, "offset", 0);
+    if (offset < 0) {
+        offset = 0;
+    }
+    int semantic_limit = cbm_mcp_get_int_arg(args, "semantic_limit", CBM_DEFAULT_SEARCH_LIMIT);
+    if (semantic_limit < 0) {
+        semantic_limit = 0;
+    } else if (semantic_limit > 500) {
+        semantic_limit = 500;
+    }
+    int semantic_offset = cbm_mcp_get_int_arg(args, "semantic_offset", 0);
+    if (semantic_offset < 0) {
+        semantic_offset = 0;
+    } else if (semantic_offset > MCP_QUERY_MAX_VISIBLE_ROWS) {
+        free(project);
+        return cbm_mcp_text_result(
+            "semantic_offset maximum is 99998 — semantic ranking is resource-bounded; "
+            "continue only with a semantic_next_offset emitted by search_graph.",
+            true);
+    }
+    /* One ranked hit beyond the requested semantic page makes has_more
+     * deterministic. Keeping the prefix through that lookahead also lets a
+     * budget-trimmed page resume at offset + rows actually emitted. */
+    int semantic_materialize_limit = semantic_offset + semantic_limit + 1;
+    int max_output_tokens = cbm_mcp_get_int_arg(args, "max_output_tokens", 3200);
+    if (max_output_tokens < 128) {
+        max_output_tokens = 128;
+    } else if (max_output_tokens > 1000000) {
+        max_output_tokens = 1000000;
+    }
+    size_t max_output_bytes =
+        (size_t)max_output_tokens * (size_t)MCP_OUTPUT_BYTES_PER_TOKEN_ESTIMATE;
 
     /* BM25 path: if `query` is set, run FTS5 full-text search with ranking
-     * and return early.  The regex/vector path below is untouched for all
-     * other callers.  If FTS5 is unavailable or the query is empty after
+     * and return early. If FTS5 is unavailable or the query is empty after
      * tokenization, fall through to the regex path. */
     char *query = cbm_mcp_get_string_arg(args, "query");
+    if (query && search_graph_arg_present(args, "semantic_query")) {
+        free(query);
+        free(project);
+        return cbm_mcp_text_result(
+            "query and semantic_query are mutually exclusive — use query for BM25 full-text "
+            "ranking or semantic_query for vector ranking, then issue a separate request for "
+            "the other mode.",
+            true);
+    }
     if (query && query[0]) {
-        int q_limit = cbm_mcp_get_int_arg(args, "limit", BM25_DEFAULT_LIMIT);
-        int q_offset = cbm_mcp_get_int_arg(args, "offset", 0);
         char *q_file_pattern = cbm_mcp_get_string_arg(args, "file_pattern");
-        char *bm25_json =
-            bm25_search(store, project, query, q_file_pattern, q_limit, q_offset, !legacy_json);
+        char *bm25_json = bm25_search(store, project, query, q_file_pattern, limit, offset,
+                                      !json_format, max_output_bytes);
         free(q_file_pattern);
         if (bm25_json) {
             free(query);
@@ -3589,8 +4475,6 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     char *relationship = cbm_mcp_get_string_arg(args, "relationship");
     bool exclude_entry_points = cbm_mcp_get_bool_arg(args, "exclude_entry_points");
     bool include_connected = cbm_mcp_get_bool_arg(args, "include_connected");
-    int limit = cbm_mcp_get_int_arg(args, "limit", CBM_DEFAULT_SEARCH_LIMIT);
-    int offset = cbm_mcp_get_int_arg(args, "offset", 0);
     int min_degree = cbm_mcp_get_int_arg(args, "min_degree", CBM_NOT_FOUND);
     int max_degree = cbm_mcp_get_int_arg(args, "max_degree", CBM_NOT_FOUND);
 
@@ -3619,192 +4503,632 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
         .max_degree = max_degree,
     };
 
-    if (!legacy_json) {
-        const char *fields[SG_MAX_EXTRA_FIELDS];
-        yyjson_doc *fields_owner = NULL;
-        char *sg_detail = cbm_mcp_get_string_arg(args, "detail");
-        bool detail_ids = sg_detail && strcmp(sg_detail, "ids") == 0;
-        free(sg_detail);
-        bool core_fields_requested = false;
-        int nfields = sg_parse_fields(args, fields, SG_MAX_EXTRA_FIELDS, &fields_owner,
-                                      &core_fields_requested);
+    const char *fields[SG_MAX_EXTRA_FIELDS];
+    yyjson_doc *fields_owner = NULL;
+    bool core_fields_requested = false;
+    int nfields =
+        sg_parse_fields(args, fields, SG_MAX_EXTRA_FIELDS, &fields_owner, &core_fields_requested);
+    char *detail_arg = cbm_mcp_get_string_arg(args, "detail");
+    bool detail_ids = detail_arg && strcmp(detail_arg, "ids") == 0;
+    free(detail_arg);
+
+    cbm_vector_result_t *vresults = NULL;
+    int vcount = 0;
+    bool sq_present = false;
+    bool sq_type_error = run_semantic_query_core(args, store, project, semantic_materialize_limit,
+                                                 &vresults, &vcount, &sq_present);
+    if (sq_type_error) {
+        if (fields_owner) {
+            yyjson_doc_free(fields_owner);
+        }
+        free(project);
+        free(label);
+        free(name_pattern);
+        free(qn_pattern);
+        free(file_pattern);
+        free(relationship);
+        return cbm_mcp_text_result(
+            "semantic_query must be an array of keyword strings, e.g. "
+            "[\"send\",\"pubsub\",\"publish\"] — not a single string. Split your query "
+            "into individual keywords; each is scored independently via per-keyword "
+            "min-cosine.",
+            true);
+    }
+
+    int semantic_available = vcount > semantic_offset ? vcount - semantic_offset : 0;
+    int semantic_page_count =
+        semantic_available < semantic_limit ? semantic_available : semantic_limit;
+    sg_semantic_page_t semantic = {
+        .results = semantic_page_count > 0 ? vresults + semantic_offset : NULL,
+        .total = vcount,
+        .offset = semantic_offset,
+        .limit = semantic_limit,
+        .total_exact = vcount < semantic_materialize_limit,
+        .present = sq_present,
+    };
+
+    /* Semantic-only calls must not prepend an unrelated, unfiltered symbol
+     * page. Combined calls retain both independently ranked result sets. */
+    bool has_filters = label || name_pattern || qn_pattern || file_pattern || relationship ||
+                       exclude_entry_points || min_degree != CBM_NOT_FOUND ||
+                       max_degree != CBM_NOT_FOUND;
+    bool semantic_only = sq_present && !has_filters;
+    cbm_search_output_t out = {0};
+    if (!semantic_only) {
+        (void)cbm_store_search(store, &params, &out);
+    }
+
+    const char *diagnostic_hint = NULL;
+    if (semantic_only && vcount == 0) {
+        diagnostic_hint = "No semantic matches; use a moderate/full index or broader keywords.";
+    } else if (!semantic_only && out.total == 0) {
+        if (name_pattern && label) {
+            diagnostic_hint = "No results; remove label or broaden name_pattern.";
+        } else if (name_pattern) {
+            diagnostic_hint = "No nodes match; check spelling or broaden the regex.";
+        } else if (label) {
+            diagnostic_hint = "No nodes have this label; inspect get_graph_schema.";
+        }
+    } else if (core_fields_requested) {
+        diagnostic_hint = "Core qn/name/label/file/lines fields are already present.";
+    }
+
+    int requested_fields = detail_ids ? 0 : nfields;
+    sg_render_plan_t plan = {
+        .returned = out.count,
+        .fields_returned = requested_fields,
+        .semantic_returned = semantic_page_count,
+        .connected_returned = !detail_ids && include_connected,
+        .core_hint_returned = diagnostic_hint != NULL,
+        .budget_hit = false,
+        .floor_exceeded = false,
+    };
+
+    char *payload = NULL;
+    for (;;) {
+        payload =
+            sg_render_payload(json_format, &out, offset, fields, requested_fields, store,
+                              relationship, !detail_ids && include_connected, detail_ids, &semantic,
+                              semantic_only, diagnostic_hint, &plan, max_output_bytes);
+        if (!payload || strlen(payload) <= max_output_bytes) {
+            break;
+        }
+        free(payload);
+        payload = NULL;
+        plan.budget_hit = true;
+
+        /* Preserve core graph answers in their stable ranked/name order.
+         * Diagnostics and opt-in enrichment yield first, then whole lower-
+         * ranked rows. No identifier, path, or field value is byte-sliced. */
+        if (plan.core_hint_returned) {
+            plan.core_hint_returned = false;
+        } else if (plan.connected_returned) {
+            plan.connected_returned = false;
+        } else if (plan.fields_returned > 0) {
+            plan.fields_returned--;
+        } else if (plan.semantic_returned > 0) {
+            plan.semantic_returned--;
+        } else if (plan.returned > 0) {
+            plan.returned--;
+        } else {
+            break;
+        }
+    }
+
+    bool identity_available = out.count > 0 || semantic_page_count > 0;
+    bool identity_returned = plan.returned > 0 || plan.semantic_returned > 0;
+    if (!payload || strlen(payload) > max_output_bytes ||
+        (identity_available && plan.budget_hit && !identity_returned)) {
+        free(payload);
+        payload = sg_budget_floor(json_format, out.total, offset, &semantic, max_output_bytes,
+                                  semantic_only);
+    }
+
+    if (vcount > 0) {
+        cbm_store_free_vector_results(vresults, vcount);
+    }
+    if (fields_owner) {
+        yyjson_doc_free(fields_owner);
+    }
+    cbm_store_search_free(&out);
+    free(project);
+    free(label);
+    free(name_pattern);
+    free(qn_pattern);
+    free(file_pattern);
+    free(relationship);
+
+    char *result = cbm_mcp_text_result(payload ? payload : "out of memory", payload == NULL);
+    free(payload);
+    return result;
+}
+
+/* query_graph response cursors bind one fully materialized result, not merely
+ * an integer offset. Re-executing an unordered query may otherwise produce a
+ * different order even while the store's coarse generation is unchanged.
+ *
+ * Token: q1.<generation>.<params-hash>.<result-digest>.<offset>.<seal>
+ *
+ * The SHA-256 materialization digest covers ordered columns and rows, explicit
+ * NULL markers, engine truncation, and the warning. The short seal makes an
+ * edited offset or token field fail closed instead of silently skipping rows.
+ * It is an integrity checksum for an opaque token, not an authentication MAC.
+ */
+enum {
+    QUERY_GRAPH_CURSOR_TOKEN_CAP = 224,
+    QUERY_GRAPH_GENERATION_CAP = 96,
+    QUERY_GRAPH_CURSOR_DIGEST_HEX_LEN = 32
+};
+
+typedef struct {
+    char generation[QUERY_GRAPH_GENERATION_CAP];
+    uint64_t params_hash;
+    char result_digest[QUERY_GRAPH_CURSOR_DIGEST_HEX_LEN + 1];
+    int offset;
+} query_graph_cursor_t;
+
+typedef struct {
+    const char *generation;
+    uint64_t params_hash;
+    const char *result_digest;
+    bool can_mint;
+} query_graph_cursor_context_t;
+
+static void query_graph_sha_u64(cbm_sha256_ctx *sha, uint64_t value) {
+    uint8_t bytes[8];
+    for (int index = 7; index >= 0; index--) {
+        bytes[index] = (uint8_t)(value & 0xffU);
+        value >>= 8U;
+    }
+    cbm_sha256_update(sha, bytes, sizeof(bytes));
+}
+
+static void query_graph_sha_field(cbm_sha256_ctx *sha, const char *value) {
+    const uint8_t present = value ? 1U : 0U;
+    cbm_sha256_update(sha, &present, sizeof(present));
+    if (!value) {
+        return;
+    }
+    size_t length = strlen(value);
+    query_graph_sha_u64(sha, (uint64_t)length);
+    cbm_sha256_update(sha, value, length);
+}
+
+static void query_graph_digest_hex(const uint8_t digest[CBM_SHA256_DIGEST_LEN],
+                                   char out[CBM_SHA256_HEX_LEN + 1]) {
+    static const char hex[] = "0123456789abcdef";
+    for (int index = 0; index < CBM_SHA256_DIGEST_LEN; index++) {
+        out[index * 2] = hex[digest[index] >> 4U];
+        out[index * 2 + 1] = hex[digest[index] & 0x0fU];
+    }
+    out[CBM_SHA256_HEX_LEN] = '\0';
+}
+
+static uint64_t query_graph_params_hash(const char *project, const char *query, const char *graph) {
+    static const char domain[] = "cbm.query_graph.params.v1";
+    cbm_sha256_ctx sha;
+    cbm_sha256_init(&sha);
+    cbm_sha256_update(&sha, domain, sizeof(domain));
+    query_graph_sha_field(&sha, project);
+    query_graph_sha_field(&sha, query);
+    query_graph_sha_field(&sha, graph);
+    uint8_t digest[CBM_SHA256_DIGEST_LEN];
+    cbm_sha256_final(&sha, digest);
+    uint64_t hash = 0;
+    for (int index = 0; index < 8; index++) {
+        hash = (hash << 8U) | digest[index];
+    }
+    return hash;
+}
+
+static void query_graph_result_digest(const cbm_cypher_result_t *result,
+                                      char out[CBM_SHA256_HEX_LEN + 1]) {
+    static const char domain[] = "cbm.query_graph.materialization.v1";
+    cbm_sha256_ctx sha;
+    cbm_sha256_init(&sha);
+    cbm_sha256_update(&sha, domain, sizeof(domain));
+    query_graph_sha_u64(&sha, (uint64_t)result->col_count);
+    query_graph_sha_u64(&sha, (uint64_t)result->row_count);
+    const uint8_t truncated = result->truncated ? 1U : 0U;
+    cbm_sha256_update(&sha, &truncated, sizeof(truncated));
+    query_graph_sha_field(&sha, result->warning);
+    for (int column = 0; column < result->col_count; column++) {
+        query_graph_sha_field(&sha, result->columns ? result->columns[column] : NULL);
+    }
+    for (int row = 0; row < result->row_count; row++) {
+        const char **cells = result->rows ? result->rows[row] : NULL;
+        for (int column = 0; column < result->col_count; column++) {
+            query_graph_sha_field(&sha, cells ? cells[column] : NULL);
+        }
+    }
+    uint8_t digest[CBM_SHA256_DIGEST_LEN];
+    cbm_sha256_final(&sha, digest);
+    query_graph_digest_hex(digest, out);
+}
+
+static void query_graph_cursor_seal(const query_graph_cursor_t *cursor, char out[17]) {
+    static const char domain[] = "cbm.query_graph.cursor.v1";
+    cbm_sha256_ctx sha;
+    cbm_sha256_init(&sha);
+    cbm_sha256_update(&sha, domain, sizeof(domain));
+    query_graph_sha_field(&sha, cursor->generation);
+    query_graph_sha_u64(&sha, cursor->params_hash);
+    query_graph_sha_field(&sha, cursor->result_digest);
+    query_graph_sha_u64(&sha, (uint64_t)cursor->offset);
+    uint8_t digest[CBM_SHA256_DIGEST_LEN];
+    cbm_sha256_final(&sha, digest);
+    char full_hex[CBM_SHA256_HEX_LEN + 1];
+    query_graph_digest_hex(digest, full_hex);
+    memcpy(out, full_hex, 16);
+    out[16] = '\0';
+}
+
+static bool query_graph_cursor_encode(const query_graph_cursor_context_t *context, int offset,
+                                      char out[QUERY_GRAPH_CURSOR_TOKEN_CAP]) {
+    if (!context || !context->can_mint || !context->generation || !context->result_digest ||
+        offset <= 0) {
+        return false;
+    }
+    query_graph_cursor_t cursor = {.params_hash = context->params_hash, .offset = offset};
+    snprintf(cursor.generation, sizeof(cursor.generation), "%s", context->generation);
+    snprintf(cursor.result_digest, sizeof(cursor.result_digest), "%.*s",
+             QUERY_GRAPH_CURSOR_DIGEST_HEX_LEN, context->result_digest);
+    char seal[17];
+    query_graph_cursor_seal(&cursor, seal);
+    int written =
+        snprintf(out, QUERY_GRAPH_CURSOR_TOKEN_CAP, "q1.%s.%016llx.%s.%d.%s", cursor.generation,
+                 (unsigned long long)cursor.params_hash, cursor.result_digest, cursor.offset, seal);
+    return written > 0 && written < QUERY_GRAPH_CURSOR_TOKEN_CAP;
+}
+
+static bool query_graph_hex_span(const char *begin, const char *end, size_t expected) {
+    if (!begin || !end || end < begin || (size_t)(end - begin) != expected) {
+        return false;
+    }
+    for (const char *digit = begin; digit < end; digit++) {
+        if (!isxdigit((unsigned char)*digit)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/* Decode and validate every token field that does not require executing the
+ * query. The materialization digest itself is checked immediately after the
+ * full query has been re-executed. */
+static const char *query_graph_cursor_decode(const char *token, const char *current_generation,
+                                             uint64_t expected_params_hash,
+                                             query_graph_cursor_t *out) {
+    static const char invalid[] =
+        "invalid_cursor: unrecognized or modified token — re-run the original query without "
+        "'cursor'";
+    memset(out, 0, sizeof(*out));
+    if (!token || strncmp(token, "q1.", 3) != 0) {
+        return invalid;
+    }
+    const char *generation_start = token + 3;
+    const char *generation_end = strchr(generation_start, '.');
+    if (!generation_end || generation_end == generation_start ||
+        (size_t)(generation_end - generation_start) >= sizeof(out->generation)) {
+        return invalid;
+    }
+    memcpy(out->generation, generation_start, (size_t)(generation_end - generation_start));
+    out->generation[generation_end - generation_start] = '\0';
+
+    const char *hash_start = generation_end + 1;
+    const char *hash_end = strchr(hash_start, '.');
+    if (!query_graph_hex_span(hash_start, hash_end, 16)) {
+        return invalid;
+    }
+    errno = 0;
+    char *parsed_end = NULL;
+    unsigned long long parsed_hash = strtoull(hash_start, &parsed_end, 16);
+    if (errno == ERANGE || parsed_end != hash_end) {
+        return invalid;
+    }
+    out->params_hash = (uint64_t)parsed_hash;
+
+    const char *digest_start = hash_end + 1;
+    const char *digest_end = strchr(digest_start, '.');
+    if (!query_graph_hex_span(digest_start, digest_end, QUERY_GRAPH_CURSOR_DIGEST_HEX_LEN)) {
+        return invalid;
+    }
+    memcpy(out->result_digest, digest_start, QUERY_GRAPH_CURSOR_DIGEST_HEX_LEN);
+    out->result_digest[QUERY_GRAPH_CURSOR_DIGEST_HEX_LEN] = '\0';
+
+    const char *offset_start = digest_end + 1;
+    const char *offset_end = strchr(offset_start, '.');
+    errno = 0;
+    long parsed_offset = offset_end ? strtol(offset_start, &parsed_end, 10) : -1;
+    if (!offset_end || offset_end == offset_start || errno == ERANGE || parsed_end != offset_end ||
+        parsed_offset <= 0 || parsed_offset > INT_MAX) {
+        return invalid;
+    }
+    out->offset = (int)parsed_offset;
+
+    const char *seal_start = offset_end + 1;
+    const char *seal_end = token + strlen(token);
+    if (!query_graph_hex_span(seal_start, seal_end, 16)) {
+        return invalid;
+    }
+    char expected_seal[17];
+    query_graph_cursor_seal(out, expected_seal);
+    if (memcmp(seal_start, expected_seal, 16) != 0) {
+        return invalid;
+    }
+    if (out->params_hash != expected_params_hash) {
+        return "cursor_params_mismatch: this cursor was issued for a different "
+               "query/project/graph — pass those arguments unchanged";
+    }
+    if (strcmp(out->generation, current_generation) != 0) {
+        return "stale_cursor: the project was reindexed since this cursor was issued — re-run "
+               "the original query without 'cursor'";
+    }
+    return NULL;
+}
+
+static bool query_graph_semantic_prefix_column(const char *column) {
+    if (!column) {
+        return false;
+    }
+    const char *leaf = strrchr(column, '.');
+    leaf = leaf ? leaf + 1 : column;
+    return strcmp(leaf, "qualified_name") == 0 || strcmp(leaf, "qn") == 0 ||
+           strcmp(leaf, "file") == 0 || strcmp(leaf, "file_path") == 0 ||
+           strcmp(leaf, "path") == 0 || strcmp(leaf, "root_path") == 0 ||
+           strcmp(leaf, "source_file") == 0;
+}
 
-        cbm_vector_result_t *vresults = NULL;
-        int vcount = 0;
-        bool sq_present = false;
-        bool sq_type_error =
-            run_semantic_query_core(args, store, project, limit, &vresults, &vcount, &sq_present);
-        if (!sq_type_error) {
-            /* Semantic-only calls get semantic results only: the legacy
-             * behavior also ran the UNFILTERED regex search and prepended
-             * up to `limit` unrelated enriched nodes to the response. */
-            bool has_filters = label || name_pattern || qn_pattern || file_pattern ||
-                               relationship || exclude_entry_points ||
-                               min_degree != CBM_NOT_FOUND || max_degree != CBM_NOT_FOUND;
-            bool semantic_only = sq_present && !has_filters;
-
-            cbm_sb_t sb;
-            cbm_sb_init(&sb);
-            cbm_search_output_t tout = {0};
-            if (!semantic_only) {
-                cbm_store_search(store, &params, &tout);
-                /* Grouped tree output is THE default; the flat table remains
-                 * only for detail:"ids" (single column — nothing to group). */
-                if (detail_ids) {
-                    emit_search_results_toon(&sb, &tout, offset, fields, nfields, detail_ids);
-                } else {
-                    emit_search_results_tree(&sb, &tout, offset, fields, nfields, store,
-                                             relationship, include_connected);
-                }
-                if (core_fields_requested) {
-                    cbm_tree_scalar_str(
-                        &sb, "hint",
-                        "some requested fields (file/name/qn/label/lines) are already core "
-                        "row columns and were skipped — `fields` is for extra property "
-                        "columns like complexity, cognitive, signature");
-                }
-                if (tout.total == 0) {
-                    if (name_pattern && label) {
-                        cbm_tree_scalar_str(&sb, "hint",
-                                            "No results. Try removing the label filter or "
-                                            "broadening the name_pattern regex.");
-                    } else if (name_pattern) {
-                        cbm_tree_scalar_str(
-                            &sb, "hint",
-                            "No nodes match this pattern. Check spelling or try a broader regex.");
-                    } else if (label) {
-                        cbm_tree_scalar_str(&sb, "hint",
-                                            "No nodes with this label. Available labels: "
-                                            "Function, Method, Class, Interface, Route, "
-                                            "Variable, Module, Package, File, Folder.");
-                    }
+static char *query_graph_tree_rows_text(const cbm_cypher_result_t *result, int row_offset,
+                                        int row_count, bool allow_directory) {
+    cbm_sb_t sb;
+    cbm_sb_init(&sb);
+    bool cell_count_safe = row_count > 0 && result->col_count > 0 &&
+                           (size_t)row_count <= SIZE_MAX / (size_t)result->col_count;
+    size_t cell_count = cell_count_safe ? (size_t)row_count * (size_t)result->col_count : 0;
+    cell_count_safe = cell_count_safe && cell_count <= SIZE_MAX / sizeof(const char *);
+    const char **cells =
+        cell_count_safe ? (const char **)malloc(cell_count * sizeof(*cells)) : NULL;
+    if (cells) {
+        for (int row = 0; row < row_count; row++) {
+            for (int col = 0; col < result->col_count; col++) {
+                cells[(size_t)row * (size_t)result->col_count + (size_t)col] =
+                    result->rows[row_offset + row][col];
+            }
+        }
+        if (allow_directory) {
+            bool *prefix_cols = calloc((size_t)result->col_count, sizeof(*prefix_cols));
+            if (prefix_cols) {
+                for (int col = 0; col < result->col_count; col++) {
+                    prefix_cols[col] = query_graph_semantic_prefix_column(result->columns[col]);
                 }
+                cbm_tree_table_rows_profiled(&sb, "rows", row_count,
+                                             (const char *const *)result->columns,
+                                             result->col_count, cells, NULL, prefix_cols);
+                free(prefix_cols);
+            } else {
+                cbm_tree_table_rows(&sb, "rows", row_count, (const char *const *)result->columns,
+                                    result->col_count, cells);
             }
-            if (vcount > 0) {
-                emit_semantic_results_toon(&sb, vresults, vcount);
-            } else if (semantic_only) {
-                static const char *const sem_cols[] = {"qn", "label", "file", "score"};
-                cbm_tree_table_header(&sb, "semantic", 0, sem_cols, 4);
-                cbm_tree_scalar_str(&sb, "hint",
-                                    "No semantic matches. semantic_query needs a moderate/full "
-                                    "index; try broader or fewer keywords.");
-            }
-            if (vcount > 0) {
-                cbm_store_free_vector_results(vresults, vcount);
-            }
-            if (fields_owner) {
-                yyjson_doc_free(fields_owner);
+        } else {
+            cbm_tree_table_header(&sb, "rows", row_count, (const char *const *)result->columns,
+                                  result->col_count);
+            for (int row = 0; row < row_count; row++) {
+                cbm_tree_row_begin(&sb);
+                for (int col = 0; col < result->col_count; col++) {
+                    cbm_tree_cell_str(&sb,
+                                      cells[(size_t)row * (size_t)result->col_count + (size_t)col],
+                                      col == 0);
+                }
+                cbm_tree_row_end(&sb);
             }
-            cbm_store_search_free(&tout);
-            free(project);
-            free(label);
-            free(name_pattern);
-            free(qn_pattern);
-            free(file_pattern);
-            free(relationship);
-            char *text = cbm_sb_finish(&sb);
-            char *result = cbm_mcp_text_result(text ? text : "out of memory", text == NULL);
-            free(text);
-            return result;
         }
-        /* semantic_query type error: fall through to the shared error text. */
-        if (fields_owner) {
-            yyjson_doc_free(fields_owner);
+        free(cells);
+    } else {
+        cbm_tree_table_header(&sb, "rows", row_count, (const char *const *)result->columns,
+                              result->col_count);
+        for (int row = 0; row < row_count; row++) {
+            cbm_tree_row_begin(&sb);
+            for (int col = 0; col < result->col_count; col++) {
+                cbm_tree_cell_str(&sb, result->rows[row_offset + row][col], col == 0);
+            }
+            cbm_tree_row_end(&sb);
         }
-        free(project);
-        free(label);
-        free(name_pattern);
-        free(qn_pattern);
-        free(file_pattern);
-        free(relationship);
-        return cbm_mcp_text_result(
-            "semantic_query must be an array of keyword strings, e.g. "
-            "[\"send\",\"pubsub\",\"publish\"] — not a single string. Split your query "
-            "into individual keywords; each is scored independently via per-keyword "
-            "min-cosine.",
-            true);
     }
+    return cbm_sb_finish(&sb);
+}
+
+static const char *query_graph_truncation_reason(const cbm_cypher_result_t *result, bool budget_hit,
+                                                 bool page_limit_hit) {
+    if (budget_hit) {
+        return "output_budget";
+    }
+    if (page_limit_hit) {
+        return "page_limit";
+    }
+    if (result->truncated) {
+        return "engine_limit";
+    }
+    return NULL;
+}
 
-    cbm_search_output_t out = {0};
-    cbm_store_search(store, &params, &out);
+static char *query_graph_tree_response_text(const cbm_cypher_result_t *result, int row_offset,
+                                            int row_count, int visible_count, bool exact_total,
+                                            bool allow_directory,
+                                            const query_graph_cursor_context_t *cursor_context) {
+    bool budget_hit = row_count < visible_count;
+    bool materialized_more = row_offset + row_count < result->row_count;
+    bool page_limit_hit = !budget_hit && materialized_more;
+    bool truncated = budget_hit || materialized_more || result->truncated;
+
+    char *rows_text = query_graph_tree_rows_text(result, row_offset, row_count, allow_directory);
+    if (!rows_text) {
+        return NULL;
+    }
+    cbm_sb_t sb;
+    cbm_sb_init(&sb);
+    cbm_sb_append(&sb, rows_text);
+    free(rows_text);
+    cbm_tree_scalar_int(&sb, "returned", row_count);
+    cbm_tree_scalar_int(&sb, "total", result->row_count);
+    cbm_tree_scalar_str(&sb, "total_relation", exact_total ? "eq" : "gte");
+    if (row_offset > 0) {
+        cbm_tree_scalar_int(&sb, "offset", row_offset);
+    }
+    cbm_tree_scalar_bool(&sb, "has_more", truncated);
+    cbm_tree_scalar_bool(&sb, "truncated", truncated);
+    const char *reason = query_graph_truncation_reason(result, budget_hit, page_limit_hit);
+    if (reason) {
+        cbm_tree_scalar_str(&sb, "truncation_reason", reason);
+    }
+    if (row_count > 0 && materialized_more) {
+        char next_cursor[QUERY_GRAPH_CURSOR_TOKEN_CAP];
+        if (query_graph_cursor_encode(cursor_context, row_offset + row_count, next_cursor)) {
+            cbm_tree_scalar_str(&sb, "next_cursor", next_cursor);
+        }
+        cbm_tree_scalar_int(&sb, "next_offset", row_offset + row_count);
+    } else if (budget_hit && row_count == 0) {
+        cbm_tree_scalar_str(&sb, "hint",
+                            "First row exceeds output budget; raise max_output_tokens.");
+    }
+    if (result->warning) {
+        cbm_tree_scalar_str(&sb, "warning", result->warning);
+    }
+    if (result->row_count == 0 && !result->truncated) {
+        cbm_tree_scalar_str(&sb, "hint",
+                            "Query returned no results. Use get_graph_schema() to see "
+                            "available labels and edge types.");
+    }
+    return cbm_sb_finish(&sb);
+}
+
+static char *query_graph_json_response_text(const cbm_cypher_result_t *result, int row_offset,
+                                            int row_count, int visible_count, bool exact_total,
+                                            const query_graph_cursor_context_t *cursor_context) {
+    bool budget_hit = row_count < visible_count;
+    bool materialized_more = row_offset + row_count < result->row_count;
+    bool page_limit_hit = !budget_hit && materialized_more;
+    bool truncated = budget_hit || materialized_more || result->truncated;
 
     yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
     yyjson_mut_val *root = yyjson_mut_obj(doc);
     yyjson_mut_doc_set_root(doc, root);
-
-    /* format:"json" = json-stringified tree: same grouped model as the
-     * default text output, structured for parsing. include_connected adds a
-     * nested per-row `connected` array — the legacy per-node-object shape is
-     * gone. */
-    {
-        const char *jfields[SG_MAX_EXTRA_FIELDS];
-        yyjson_doc *jfields_owner = NULL;
-        int jnfields = sg_parse_fields(args, jfields, SG_MAX_EXTRA_FIELDS, &jfields_owner, NULL);
-        emit_search_results_tree_json(doc, root, &out, offset, jfields, jnfields, store,
-                                      relationship, include_connected);
-        if (jfields_owner) {
-            yyjson_doc_free(jfields_owner);
-        }
+    yyjson_mut_val *cols = yyjson_mut_arr(doc);
+    for (int i = 0; i < result->col_count; i++) {
+        yyjson_mut_arr_add_str(doc, cols, result->columns[i]);
     }
-
-    /* Add diagnostic hint when zero results */
-    if (out.total == 0) {
-        if (name_pattern && label) {
-            yyjson_mut_obj_add_str(
-                doc, root, "hint",
-                "No results. Try removing the label filter or broadening the name_pattern regex.");
-        } else if (name_pattern) {
-            yyjson_mut_obj_add_str(
-                doc, root, "hint",
-                "No nodes match this pattern. Check spelling or try a broader regex.");
-        } else if (label) {
-            yyjson_mut_obj_add_str(
-                doc, root, "hint",
-                "No nodes with this label. Available labels: Function, Method, Class, "
-                "Interface, Route, Variable, Module, Package, File, Folder.");
+    yyjson_mut_obj_add_val(doc, root, "columns", cols);
+    yyjson_mut_val *rows = yyjson_mut_arr(doc);
+    for (int row_index = 0; row_index < row_count; row_index++) {
+        yyjson_mut_val *row = yyjson_mut_arr(doc);
+        for (int col = 0; col < result->col_count; col++) {
+            yyjson_mut_arr_add_str(doc, row, result->rows[row_offset + row_index][col]);
         }
+        yyjson_mut_arr_add_val(rows, row);
     }
-
-    bool sq_type_error = run_semantic_query(doc, root, args, store, project, limit);
-
-    if (sq_type_error) {
-        yyjson_mut_doc_free(doc);
-        cbm_store_search_free(&out);
-        free(project);
-        free(label);
-        free(name_pattern);
-        free(qn_pattern);
-        free(file_pattern);
-        free(relationship);
-        return cbm_mcp_text_result(
-            "semantic_query must be an array of keyword strings, e.g. "
-            "[\"send\",\"pubsub\",\"publish\"] — not a single string. Split your query "
-            "into individual keywords; each is scored independently via per-keyword "
-            "min-cosine.",
-            true);
+    yyjson_mut_obj_add_val(doc, root, "rows", rows);
+    yyjson_mut_obj_add_int(doc, root, "returned", row_count);
+    yyjson_mut_obj_add_int(doc, root, "total", result->row_count);
+    yyjson_mut_obj_add_str(doc, root, "total_relation", exact_total ? "eq" : "gte");
+    if (row_offset > 0) {
+        yyjson_mut_obj_add_int(doc, root, "offset", row_offset);
+    }
+    yyjson_mut_obj_add_bool(doc, root, "has_more", truncated);
+    yyjson_mut_obj_add_bool(doc, root, "truncated", truncated);
+    const char *reason = query_graph_truncation_reason(result, budget_hit, page_limit_hit);
+    if (reason) {
+        yyjson_mut_obj_add_str(doc, root, "truncation_reason", reason);
+    }
+    if (row_count > 0 && materialized_more) {
+        char next_cursor[QUERY_GRAPH_CURSOR_TOKEN_CAP];
+        if (query_graph_cursor_encode(cursor_context, row_offset + row_count, next_cursor)) {
+            yyjson_mut_obj_add_strcpy(doc, root, "next_cursor", next_cursor);
+        }
+        yyjson_mut_obj_add_int(doc, root, "next_offset", row_offset + row_count);
+    } else if (budget_hit && row_count == 0) {
+        yyjson_mut_obj_add_str(doc, root, "hint",
+                               "First row exceeds output budget; raise max_output_tokens.");
+    }
+    if (result->warning) {
+        yyjson_mut_obj_add_str(doc, root, "warning", result->warning);
+    }
+    if (result->row_count == 0 && !result->truncated) {
+        yyjson_mut_obj_add_str(
+            doc, root, "hint",
+            "Query returned no results. Use get_graph_schema() to see available labels and "
+            "edge types.");
     }
-
     char *json = yy_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
-    cbm_store_search_free(&out);
+    return json;
+}
 
-    free(project);
-    free(label);
-    free(name_pattern);
-    free(qn_pattern);
-    free(file_pattern);
-    free(relationship);
+/* A pathological query can make the column expression itself larger than the
+ * requested response budget. Do not byte-slice that semantic key. Return a
+ * small, explicit recovery envelope and let the caller raise the budget to
+ * retrieve the exact columns and first row. */
+static char *query_graph_budget_floor_text(const cbm_cypher_result_t *result, int row_offset,
+                                           bool exact_total, bool json_format) {
+    if (json_format) {
+        yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+        yyjson_mut_val *root = yyjson_mut_obj(doc);
+        yyjson_mut_doc_set_root(doc, root);
+        yyjson_mut_obj_add_val(doc, root, "columns", yyjson_mut_arr(doc));
+        yyjson_mut_obj_add_val(doc, root, "rows", yyjson_mut_arr(doc));
+        yyjson_mut_obj_add_bool(doc, root, "columns_omitted", true);
+        yyjson_mut_obj_add_int(doc, root, "returned", 0);
+        yyjson_mut_obj_add_int(doc, root, "total", result->row_count);
+        yyjson_mut_obj_add_str(doc, root, "total_relation", exact_total ? "eq" : "gte");
+        if (row_offset > 0) {
+            yyjson_mut_obj_add_int(doc, root, "offset", row_offset);
+        }
+        yyjson_mut_obj_add_bool(doc, root, "has_more", true);
+        yyjson_mut_obj_add_bool(doc, root, "truncated", true);
+        yyjson_mut_obj_add_str(doc, root, "truncation_reason", "output_budget");
+        yyjson_mut_obj_add_str(doc, root, "hint",
+                               "Column metadata or first row exceeds output budget; raise "
+                               "max_output_tokens.");
+        char *json = yy_doc_to_str(doc);
+        yyjson_mut_doc_free(doc);
+        return json;
+    }
 
-    char *result = cbm_mcp_text_result(json, false);
-    free(json);
-    return result;
+    cbm_sb_t sb;
+    cbm_sb_init(&sb);
+    cbm_tree_scalar_int(&sb, "rows", 0);
+    cbm_tree_scalar_bool(&sb, "columns_omitted", true);
+    cbm_tree_scalar_int(&sb, "returned", 0);
+    cbm_tree_scalar_int(&sb, "total", result->row_count);
+    cbm_tree_scalar_str(&sb, "total_relation", exact_total ? "eq" : "gte");
+    if (row_offset > 0) {
+        cbm_tree_scalar_int(&sb, "offset", row_offset);
+    }
+    cbm_tree_scalar_bool(&sb, "has_more", true);
+    cbm_tree_scalar_bool(&sb, "truncated", true);
+    cbm_tree_scalar_str(&sb, "truncation_reason", "output_budget");
+    cbm_tree_scalar_str(&sb, "hint",
+                        "Column metadata or first row exceeds output budget; raise "
+                        "max_output_tokens.");
+    return cbm_sb_finish(&sb);
 }
 
 static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
     char *query = cbm_mcp_get_string_arg(args, "query");
     char *project = get_project_arg(args);
     cbm_store_t *store = resolve_store(srv, project);
-    int max_rows = cbm_mcp_get_int_arg(args, "max_rows", 0);
+    int visible_limit = cbm_mcp_get_int_arg(args, "max_rows", 200);
+    if (visible_limit == 0 || visible_limit > MCP_QUERY_MAX_VISIBLE_ROWS) {
+        /* compatibility: max_rows=0 used to mean engine default */
+        visible_limit = MCP_QUERY_MAX_VISIBLE_ROWS;
+    } else if (visible_limit < 0) {
+        visible_limit = 1;
+    }
+    int requested_offset = cbm_mcp_get_int_arg(args, "offset", 0);
+    int row_offset = requested_offset;
+    if (row_offset < 0) {
+        row_offset = 0;
+    }
+    char *cursor_arg = cbm_mcp_get_string_arg(args, "cursor");
 
     /* graph="missed" (#963): run the SAME cypher against the derived
      * miss-graph view (shadow project "<project>::missed") instead of the
@@ -3814,10 +5138,12 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
     free(graph_arg);
 
     if (!query) {
+        free(cursor_arg);
         free(project);
         return cbm_mcp_text_result("query is required", true);
     }
     if (missed_graph && !project) {
+        free(cursor_arg);
         free(query);
         return cbm_mcp_text_result("project is required when graph=\"missed\"", true);
     }
@@ -3825,6 +5151,7 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
         char *_err = build_project_list_error("project not found or not indexed");
         char *_res = cbm_mcp_text_result(_err, true);
         free(_err);
+        free(cursor_arg);
         free(project);
         free(query);
         return _res;
@@ -3832,6 +5159,7 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
 
     char *not_indexed = verify_project_indexed(store, project);
     if (not_indexed) {
+        free(cursor_arg);
         free(project);
         free(query);
         return not_indexed;
@@ -3844,17 +5172,86 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
         cypher_project = covproj;
     }
 
+    char generation[QUERY_GRAPH_GENERATION_CAP] = "";
+    int generation_rc = cbm_store_generation(store, generation, sizeof(generation));
+    if (generation_rc != CBM_STORE_OK) {
+        free(cursor_arg);
+        free(project);
+        free(query);
+        return cbm_mcp_text_result(
+            "index_metadata_error: generation metadata is unreadable; reindex before querying",
+            true);
+    }
+    bool generation_available = generation[0] != '\0';
+    const char *effective_project = project ? project : srv->current_project;
+    uint64_t params_hash =
+        query_graph_params_hash(effective_project, query, missed_graph ? "missed" : "code");
+    query_graph_cursor_t cursor = {0};
+    if (cursor_arg) {
+        if (requested_offset != 0) {
+            free(cursor_arg);
+            free(project);
+            free(query);
+            return cbm_mcp_text_result(
+                "invalid_params: cursor cannot be combined with a nonzero offset", true);
+        }
+        if (!generation_available || strcmp(generation, "legacy") == 0) {
+            free(cursor_arg);
+            free(project);
+            free(query);
+            return cbm_mcp_text_result(
+                "cursor_unsupported: this index predates generation tracking; reindex before "
+                "using snapshot pagination",
+                true);
+        }
+        const char *cursor_error =
+            query_graph_cursor_decode(cursor_arg, generation, params_hash, &cursor);
+        if (cursor_error) {
+            free(cursor_arg);
+            free(project);
+            free(query);
+            return cbm_mcp_text_result(cursor_error, true);
+        }
+        row_offset = cursor.offset;
+    }
+
     cbm_cypher_result_t result = {0};
-    int rc = cbm_cypher_execute(store, query, cypher_project, max_rows, &result);
+    /* `max_rows` is a presentation budget, never an evaluation budget.
+     * Executing at visible_limit+1 corrupts ORDER BY, DISTINCT, aggregation,
+     * and SKIP semantics before serialization gets a chance to trim rows.
+     * Zero preserves the engine's established 100k safety ceiling. */
+    int rc = cbm_cypher_execute(store, query, cypher_project, 0, &result);
 
     if (rc < 0) {
         char *err_msg = result.error ? result.error : "query execution failed";
         char *resp = cbm_mcp_text_result(err_msg, true);
         cbm_cypher_result_free(&result);
+        free(cursor_arg);
+        free(query);
+        free(project);
+        return resp;
+    }
+
+    char result_digest[CBM_SHA256_HEX_LEN + 1];
+    query_graph_result_digest(&result, result_digest);
+    if (cursor_arg &&
+        strncmp(cursor.result_digest, result_digest, QUERY_GRAPH_CURSOR_DIGEST_HEX_LEN) != 0) {
+        char *resp = cbm_mcp_text_result(
+            "stale_cursor: the complete query materialization changed since this cursor was "
+            "issued; re-run the original query without 'cursor'",
+            true);
+        cbm_cypher_result_free(&result);
+        free(cursor_arg);
         free(query);
         free(project);
         return resp;
     }
+    query_graph_cursor_context_t cursor_context = {
+        .generation = generation,
+        .params_hash = params_hash,
+        .result_digest = result_digest,
+        .can_mint = generation_available && strcmp(generation, "legacy") != 0,
+    };
 
     /* Response encoding: TOON table by default (the columns double as the
      * table header); format:"json" restores the legacy columns/rows arrays. */
@@ -3862,67 +5259,138 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
     bool qg_legacy_json = qg_format && strcmp(qg_format, "json") == 0;
     free(qg_format);
 
-    char *json = NULL;
-    if (!qg_legacy_json) {
-        cbm_sb_t sb;
-        cbm_sb_init(&sb);
-        cbm_tree_table_header(&sb, "rows", result.row_count, (const char *const *)result.columns,
-                              result.col_count);
-        for (int r = 0; r < result.row_count; r++) {
-            cbm_tree_row_begin(&sb);
-            for (int c = 0; c < result.col_count; c++) {
-                cbm_tree_cell_str(&sb, result.rows[r][c], c == 0);
-            }
-            cbm_tree_row_end(&sb);
-        }
-        cbm_tree_scalar_int(&sb, "total", result.row_count);
-        if (result.warning) {
-            cbm_tree_scalar_str(&sb, "warning", result.warning);
+    int materialized_rows = row_offset < result.row_count ? result.row_count - row_offset : 0;
+    int available_rows = materialized_rows < visible_limit ? materialized_rows : visible_limit;
+    int max_output_tokens = cbm_mcp_get_int_arg(args, "max_output_tokens", 3200);
+    if (max_output_tokens < 128) {
+        max_output_tokens = 128;
+    } else if (max_output_tokens > 1000000) {
+        max_output_tokens = 1000000;
+    }
+    size_t byte_budget = (size_t)max_output_tokens * (size_t)MCP_OUTPUT_BYTES_PER_TOKEN_ESTIMATE;
+    size_t estimated = 256U;
+    for (int c = 0; c < result.col_count; c++) {
+        estimated += strlen(result.columns[c]) + 1U;
+    }
+    int raw_fit_rows = 0;
+    for (int r = 0; r < available_rows; r++) {
+        size_t row_bytes = 4U;
+        for (int c = 0; c < result.col_count; c++) {
+            size_t cell_bytes =
+                strlen(result.rows[row_offset + r][c] ? result.rows[row_offset + r][c] : "") + 1U;
+            row_bytes = row_bytes > SIZE_MAX - cell_bytes ? SIZE_MAX : row_bytes + cell_bytes;
         }
-        if (result.row_count == 0) {
-            cbm_tree_scalar_str(&sb, "hint",
-                                "Query returned no results. Use get_graph_schema() to see "
-                                "available labels and edge types.");
+        if (estimated <= byte_budget && row_bytes <= byte_budget - estimated) {
+            raw_fit_rows = r + 1;
         }
-        json = cbm_sb_finish(&sb);
-    } else {
-        yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
-        yyjson_mut_val *root = yyjson_mut_obj(doc);
-        yyjson_mut_doc_set_root(doc, root);
+        estimated = estimated > SIZE_MAX - row_bytes ? SIZE_MAX : estimated + row_bytes;
+    }
 
-        /* columns */
-        yyjson_mut_val *cols = yyjson_mut_arr(doc);
-        for (int i = 0; i < result.col_count; i++) {
-            yyjson_mut_arr_add_str(doc, cols, result.columns[i]);
-        }
-        yyjson_mut_obj_add_val(doc, root, "columns", cols);
+    /* Exact sizing is bounded near the conservative raw estimate. This avoids
+     * constructing a 100k-row candidate merely to learn that the default
+     * 3,200-token response can hold a few hundred rows. */
+    int exact_upper = raw_fit_rows;
+    if (exact_upper < available_rows) {
+        int headroom = available_rows - exact_upper < 32 ? available_rows - exact_upper : 32;
+        exact_upper += headroom;
+    }
+    bool exact_total = !result.truncated;
 
-        /* rows */
-        yyjson_mut_val *rows = yyjson_mut_arr(doc);
-        for (int r = 0; r < result.row_count; r++) {
-            yyjson_mut_val *row = yyjson_mut_arr(doc);
-            for (int c = 0; c < result.col_count; c++) {
-                yyjson_mut_arr_add_str(doc, row, result.rows[r][c]);
+    int output_rows = 0;
+    char *json = NULL;
+    if (qg_legacy_json) {
+        /* JSON size is monotone in the row prefix, so exact serialized probes
+         * safely account for escaping and syntax overhead. */
+        int low = 0;
+        int high = exact_upper;
+        while (low <= high) {
+            int middle = low + (high - low) / 2;
+            char *candidate = query_graph_json_response_text(
+                &result, row_offset, middle, available_rows, exact_total, &cursor_context);
+            bool fits = candidate && strlen(candidate) <= byte_budget;
+            free(candidate);
+            if (fits) {
+                output_rows = middle;
+                low = middle + 1;
+            } else {
+                high = middle - 1;
             }
-            yyjson_mut_arr_add_val(rows, row);
-        }
-        yyjson_mut_obj_add_val(doc, root, "rows", rows);
-        yyjson_mut_obj_add_int(doc, root, "total", result.row_count);
-        if (result.warning) {
-            yyjson_mut_obj_add_str(doc, root, "warning", result.warning);
         }
+        json = query_graph_json_response_text(&result, row_offset, output_rows, available_rows,
+                                              exact_total, &cursor_context);
+    } else {
+        /* A repeated multi-KiB path/QN prefix can make the complete compact
+         * page tiny even when the raw estimate is enormous. Probe that common
+         * directory-shaped case once, under a hard construction guard, before
+         * using the conservative raw estimate. */
+        enum { QUERY_COMPACT_FULL_PROBE_MAX_BYTES = 16 * 1024 * 1024 };
+        if (available_rows <= 512 && estimated <= QUERY_COMPACT_FULL_PROBE_MAX_BYTES) {
+            char *candidate =
+                query_graph_tree_response_text(&result, row_offset, available_rows, available_rows,
+                                               exact_total, true, &cursor_context);
+            if (candidate && strlen(candidate) <= byte_budget) {
+                output_rows = available_rows;
+                json = candidate;
+            } else {
+                free(candidate);
+            }
+        }
+
+        if (!json) {
+            /* Establish a monotone direct-table baseline first. */
+            int low = 0;
+            int high = exact_upper;
+            while (low <= high) {
+                int middle = low + (high - low) / 2;
+                char *candidate =
+                    query_graph_tree_response_text(&result, row_offset, middle, available_rows,
+                                                   exact_total, false, &cursor_context);
+                bool fits = candidate && strlen(candidate) <= byte_budget;
+                free(candidate);
+                if (fits) {
+                    output_rows = middle;
+                    low = middle + 1;
+                } else {
+                    high = middle - 1;
+                }
+            }
 
-        if (result.row_count == 0) {
-            yyjson_mut_obj_add_str(
-                doc, root, "hint",
-                "Query returned no results. Use get_graph_schema() to see available labels and "
-                "edge types.");
+            /* Directory activation can make N+1 rows smaller than N. For the lean
+             * default-sized answer, inspect every bounded candidate in descending
+             * order instead of making an invalid binary-search assumption. Skip
+             * this expansion for enormous raw payloads; the direct fit remains a
+             * truthful, bounded answer and can still be encoded more compactly. */
+            int compact_upper = exact_upper;
+            size_t expanded_budget = byte_budget <= SIZE_MAX / 4U ? byte_budget * 4U : SIZE_MAX;
+            if (available_rows <= 512 && estimated <= expanded_budget) {
+                compact_upper = available_rows;
+            }
+            for (int candidate_rows = compact_upper; candidate_rows > output_rows;
+                 candidate_rows--) {
+                char *candidate = query_graph_tree_response_text(
+                    &result, row_offset, candidate_rows, available_rows, exact_total, true,
+                    &cursor_context);
+                bool fits = candidate && strlen(candidate) <= byte_budget;
+                if (fits) {
+                    output_rows = candidate_rows;
+                    json = candidate;
+                    break;
+                }
+                free(candidate);
+            }
+            if (!json) {
+                json =
+                    query_graph_tree_response_text(&result, row_offset, output_rows, available_rows,
+                                                   exact_total, true, &cursor_context);
+            }
         }
-
-        json = yy_doc_to_str(doc);
-        yyjson_mut_doc_free(doc);
+    }
+    if (json && output_rows == 0 && strlen(json) > byte_budget) {
+        free(json);
+        json = query_graph_budget_floor_text(&result, row_offset, exact_total, qg_legacy_json);
     }
     cbm_cypher_result_free(&result);
+    free(cursor_arg);
     free(query);
     free(project);
 
@@ -3937,10 +5405,12 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
 enum { COVERAGE_FILE_CAP = 500 };
 
 static void add_coverage_report(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_store_t *store,
-                                const char *project) {
+                                const char *project, const char *indexed_at, int sample_limit) {
     cbm_coverage_row_t *rows = NULL;
     int count = 0;
     (void)cbm_store_coverage_get(store, project, &rows, &count);
+    cbm_coverage_meta_t meta = {0};
+    bool have_meta = cbm_store_coverage_meta_get(store, project, &meta) == CBM_STORE_OK;
 
     yyjson_mut_val *pp_files = yyjson_mut_arr(doc);
     yyjson_mut_val *sk_files = yyjson_mut_arr(doc);
@@ -3953,7 +5423,7 @@ static void add_coverage_report(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_s
     for (int i = 0; i < count; i++) {
         const char *kind = rows[i].kind ? rows[i].kind : "";
         if (strcmp(kind, "parse_partial") == 0) {
-            if (pp_n < COVERAGE_FILE_CAP) {
+            if (pp_n < sample_limit) {
                 yyjson_mut_val *fe = yyjson_mut_obj(doc);
                 yyjson_mut_obj_add_strcpy(doc, fe, "path", rows[i].rel_path);
                 yyjson_mut_obj_add_strcpy(doc, fe, "error_ranges",
@@ -3962,12 +5432,12 @@ static void add_coverage_report(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_s
             }
             pp_n++;
         } else if (strcmp(kind, "not_indexed_dir") == 0) {
-            if (ni_dir_n < COVERAGE_FILE_CAP) {
+            if (ni_dir_n < sample_limit) {
                 yyjson_mut_arr_add_strcpy(doc, ni_dirs, rows[i].rel_path);
             }
             ni_dir_n++;
         } else if (strcmp(kind, "not_indexed_file") == 0) {
-            if (ni_file_n < COVERAGE_FILE_CAP) {
+            if (ni_file_n < sample_limit) {
                 yyjson_mut_val *fe = yyjson_mut_obj(doc);
                 yyjson_mut_obj_add_strcpy(doc, fe, "path", rows[i].rel_path);
                 yyjson_mut_obj_add_strcpy(doc, fe, "reason", rows[i].detail ? rows[i].detail : "");
@@ -3975,7 +5445,7 @@ static void add_coverage_report(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_s
             }
             ni_file_n++;
         } else {
-            if (sk_n < COVERAGE_FILE_CAP) {
+            if (sk_n < sample_limit) {
                 yyjson_mut_val *fe = yyjson_mut_obj(doc);
                 yyjson_mut_obj_add_strcpy(doc, fe, "path", rows[i].rel_path);
                 yyjson_mut_obj_add_strcpy(doc, fe, "reason", rows[i].detail ? rows[i].detail : "");
@@ -3987,16 +5457,36 @@ static void add_coverage_report(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_s
     }
     cbm_store_free_coverage(rows, count);
 
+    /* Discovery retains a bounded sample of ignored files but records the
+     * exact uncapped total atomically beside it. Counts-only status must use
+     * that authoritative total: reporting only the stored rows makes a lean
+     * response look complete precisely when the discovery cap was hit. */
+    bool generation_matches =
+        have_meta && indexed_at && meta.generation && strcmp(indexed_at, meta.generation) == 0;
+    bool ignored_total_authoritative = generation_matches && meta.ignored_files_total >= ni_file_n;
+    int ni_file_total = ni_file_n;
+    if (ignored_total_authoritative) {
+        ni_file_total = meta.ignored_files_total;
+    }
+    cbm_store_coverage_meta_clear(&meta);
+    int ni_files_shown = ni_file_n < sample_limit ? ni_file_n : sample_limit;
+
     yyjson_mut_val *pp = yyjson_mut_obj(doc);
     yyjson_mut_obj_add_val(doc, pp, "files", pp_files);
     yyjson_mut_obj_add_int(doc, pp, "count", pp_n);
-    yyjson_mut_obj_add_bool(doc, pp, "truncated", pp_n > COVERAGE_FILE_CAP);
+    yyjson_mut_obj_add_bool(doc, pp, "truncated", pp_n > sample_limit);
+    if (pp_n > sample_limit) {
+        yyjson_mut_obj_add_int(doc, pp, "omitted", pp_n - sample_limit);
+    }
     yyjson_mut_obj_add_val(doc, root, "parse_partial", pp);
 
     yyjson_mut_val *sk = yyjson_mut_obj(doc);
     yyjson_mut_obj_add_val(doc, sk, "files", sk_files);
     yyjson_mut_obj_add_int(doc, sk, "count", sk_n);
-    yyjson_mut_obj_add_bool(doc, sk, "truncated", sk_n > COVERAGE_FILE_CAP);
+    yyjson_mut_obj_add_bool(doc, sk, "truncated", sk_n > sample_limit);
+    if (sk_n > sample_limit) {
+        yyjson_mut_obj_add_int(doc, sk, "omitted", sk_n - sample_limit);
+    }
     yyjson_mut_obj_add_val(doc, root, "skipped", sk);
 
     /* By-design exclusions (#963 "purposely not indexed"): a deliberate,
@@ -4007,10 +5497,19 @@ static void add_coverage_report(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_s
     yyjson_mut_obj_add_val(doc, ni, "dirs", ni_dirs);
     yyjson_mut_obj_add_int(doc, ni, "dirs_count", ni_dir_n);
     yyjson_mut_obj_add_val(doc, ni, "files", ni_files);
-    yyjson_mut_obj_add_int(doc, ni, "files_count", ni_file_n);
+    yyjson_mut_obj_add_int(doc, ni, "files_count", ni_file_total);
+    if (!ignored_total_authoritative) {
+        yyjson_mut_obj_add_str(doc, ni, "files_count_relation", "gte");
+    }
     yyjson_mut_obj_add_bool(doc, ni, "truncated",
-                            ni_dir_n > COVERAGE_FILE_CAP || ni_file_n > COVERAGE_FILE_CAP);
-    if (ni_dir_n > 0 || ni_file_n > 0) {
+                            ni_dir_n > sample_limit || ni_file_total > ni_files_shown);
+    if (ni_dir_n > sample_limit) {
+        yyjson_mut_obj_add_int(doc, ni, "dirs_omitted", ni_dir_n - sample_limit);
+    }
+    if (ni_file_total > ni_files_shown) {
+        yyjson_mut_obj_add_int(doc, ni, "files_omitted", ni_file_total - ni_files_shown);
+    }
+    if (sample_limit > 0 && (ni_dir_n > 0 || ni_file_total > 0)) {
         yyjson_mut_obj_add_str(doc, ni, "note",
                                "Purposely not indexed — excluded BY DESIGN via "
                                "gitignore/.cbmignore/skip-lists (see each file's reason). Not an "
@@ -4018,7 +5517,7 @@ static void add_coverage_report(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_s
     }
     yyjson_mut_obj_add_val(doc, root, "not_indexed", ni);
 
-    if (pp_n > 0 || sk_n > 0) {
+    if (sample_limit > 0 && (pp_n > 0 || sk_n > 0)) {
         yyjson_mut_obj_add_str(
             doc, root, "coverage_note",
             "Best-effort signal, not a completeness guarantee: parse_partial files WERE indexed, "
@@ -4147,9 +5646,9 @@ static const char *coverage_path_freshness(cbm_store_t *store, const char *proje
     return matches ? "metadata_match" : "metadata_changed";
 }
 
-static void coverage_add_ranges(yyjson_mut_doc *doc, yyjson_mut_val *row, const char *detail) {
+static bool coverage_add_ranges(yyjson_mut_doc *doc, yyjson_mut_val *row, const char *detail) {
     if (!detail || !detail[0]) {
-        return;
+        return false;
     }
     yyjson_mut_val *ranges = yyjson_mut_arr(doc);
     const char *p = detail;
@@ -4191,22 +5690,34 @@ static void coverage_add_ranges(yyjson_mut_doc *doc, yyjson_mut_val *row, const
     }
     if (emitted > 0) {
         yyjson_mut_obj_add_val(doc, row, "ranges", ranges);
+        if (emitted == COVERAGE_RANGE_MAX && *p) {
+            yyjson_mut_obj_add_bool(doc, row, "ranges_truncated", true);
+        }
     }
+    return emitted > 0;
 }
 
 static void coverage_add_row_json(yyjson_mut_doc *doc, yyjson_mut_val *array,
-                                  const cbm_coverage_row_t *row, const char *requested_path) {
+                                  const cbm_coverage_row_t *row, const char *requested_path,
+                                  bool diagnostics_full) {
     yyjson_mut_val *item = yyjson_mut_obj(doc);
     yyjson_mut_obj_add_strcpy(doc, item, "path", row->rel_path ? row->rel_path : "");
     yyjson_mut_obj_add_strcpy(doc, item, "kind", row->kind ? row->kind : "");
-    yyjson_mut_obj_add_strcpy(doc, item, "detail", row->detail ? row->detail : "");
     if (requested_path) {
         yyjson_mut_obj_add_str(
             doc, item, "match",
             row->rel_path && strcmp(row->rel_path, requested_path) == 0 ? "exact" : "ancestor");
     }
+    bool ranges_added = false;
     if (row->kind && strcmp(row->kind, "parse_partial") == 0) {
-        coverage_add_ranges(doc, item, row->detail);
+        ranges_added = coverage_add_ranges(doc, item, row->detail);
+    }
+    /* A parse_partial detail such as "3-4,9" is byte-for-byte redundant once
+     * represented as typed ranges. Preserve raw storage diagnostics on request,
+     * and preserve every non-range detail by default because it may explain why
+     * a file was skipped or excluded. */
+    if (diagnostics_full || !ranges_added) {
+        yyjson_mut_obj_add_strcpy(doc, item, "detail", row->detail ? row->detail : "");
     }
     yyjson_mut_arr_add_val(array, item);
 }
@@ -4288,6 +5799,19 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
             "paths or scopes is required (arrays; max 128 paths and 32 scopes)", true);
     }
 
+    int path_limit = cbm_mcp_get_int_arg(args, "path_limit", 20);
+    int path_offset = cbm_mcp_get_int_arg(args, "path_offset", 0);
+    if (path_limit < 1) {
+        path_limit = 1;
+    } else if (path_limit > COVERAGE_PATH_MAX) {
+        path_limit = COVERAGE_PATH_MAX;
+    }
+    if (path_offset < 0) {
+        path_offset = 0;
+    }
+    char *diagnostics = cbm_mcp_get_string_arg(args, "diagnostics");
+    bool diagnostics_full = diagnostics && strcmp(diagnostics, "full") == 0;
+
     cbm_project_t proj = {0};
     bool have_project = cbm_store_get_project(store, project, &proj) == CBM_STORE_OK;
     cbm_coverage_meta_t meta = {0};
@@ -4325,11 +5849,15 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
     yyjson_mut_obj_add_val(doc, root, "metadata", meta_obj);
 
     yyjson_mut_val *path_results = yyjson_mut_arr(doc);
+    int path_returned = 0;
     size_t idx;
     size_t max;
     yyjson_val *value;
     if (paths) {
         yyjson_arr_foreach(paths, idx, max, value) {
+            if (idx < (size_t)path_offset || idx >= (size_t)path_offset + (size_t)path_limit) {
+                continue;
+            }
             yyjson_mut_val *item = yyjson_mut_obj(doc);
             const char *input = yyjson_is_str(value) ? yyjson_get_str(value) : NULL;
             yyjson_mut_obj_add_strcpy(doc, item, "requested_path", input ? input : "");
@@ -4344,6 +5872,7 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
                 yyjson_mut_obj_add_str(doc, item, "recommended_action",
                                        "use_project_relative_path");
                 yyjson_mut_arr_add_val(path_results, item);
+                path_returned++;
                 continue;
             }
             yyjson_mut_obj_add_strcpy(doc, item, "path", rel);
@@ -4367,16 +5896,24 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
                                       coverage_recommended_action(status, freshness));
             yyjson_mut_val *coverage = yyjson_mut_arr(doc);
             for (int i = 0; i < row_count; i++) {
-                coverage_add_row_json(doc, coverage, &rows[i], rel);
+                coverage_add_row_json(doc, coverage, &rows[i], rel, diagnostics_full);
             }
             yyjson_mut_obj_add_val(doc, item, "coverage", coverage);
             cbm_store_free_coverage(rows, row_count);
             yyjson_mut_arr_add_val(path_results, item);
+            path_returned++;
         }
     }
     yyjson_mut_obj_add_val(doc, root, "paths", path_results);
+    yyjson_mut_obj_add_int(doc, root, "path_total", (int64_t)path_count);
+    yyjson_mut_obj_add_int(doc, root, "path_returned", path_returned);
+    bool path_has_more = (size_t)path_offset + (size_t)path_returned < path_count;
+    yyjson_mut_obj_add_bool(doc, root, "path_has_more", path_has_more);
+    if (path_has_more) {
+        yyjson_mut_obj_add_int(doc, root, "path_next_offset", path_offset + path_returned);
+    }
 
-    int scope_limit = cbm_mcp_get_int_arg(args, "scope_limit", COVERAGE_SCOPE_DEFAULT_LIMIT);
+    int scope_limit = cbm_mcp_get_int_arg(args, "scope_limit", 20);
     int scope_offset = cbm_mcp_get_int_arg(args, "scope_offset", 0);
     if (scope_limit < 1) {
         scope_limit = 1;
@@ -4387,6 +5924,8 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
         scope_offset = 0;
     }
     yyjson_mut_val *scope_results = yyjson_mut_arr(doc);
+    int scope_total = 0;
+    int scope_returned = 0;
     if (scopes) {
         yyjson_arr_foreach(scopes, idx, max, value) {
             yyjson_mut_val *item = yyjson_mut_obj(doc);
@@ -4412,15 +5951,28 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
                 yyjson_mut_obj_add_str(doc, item, "coverage_lookup", "error");
             }
             yyjson_mut_obj_add_int(doc, item, "total", row_count);
-            int start = scope_offset < row_count ? scope_offset : row_count;
-            int end = start + scope_limit < row_count ? start + scope_limit : row_count;
-            yyjson_mut_obj_add_bool(doc, item, "has_more", end < row_count);
-            if (end < row_count) {
-                yyjson_mut_obj_add_int(doc, item, "next_offset", end);
-            }
+            int flat_start = scope_total;
+            int flat_end = flat_start + row_count;
+            int page_start = scope_offset;
+            int page_end = scope_offset + scope_limit;
+            int start = page_start > flat_start ? page_start - flat_start : 0;
+            int end = page_end < flat_end ? page_end - flat_start : row_count;
+            if (start < 0) {
+                start = 0;
+            } else if (start > row_count) {
+                start = row_count;
+            }
+            if (end < start) {
+                end = start;
+            } else if (end > row_count) {
+                end = row_count;
+            }
+            int returned = end - start;
+            yyjson_mut_obj_add_int(doc, item, "returned", returned);
+            yyjson_mut_obj_add_bool(doc, item, "truncated", returned < row_count);
             yyjson_mut_val *entries = yyjson_mut_arr(doc);
             for (int i = start; i < end; i++) {
-                coverage_add_row_json(doc, entries, &rows[i], NULL);
+                coverage_add_row_json(doc, entries, &rows[i], NULL, diagnostics_full);
             }
             yyjson_mut_obj_add_val(doc, item, "entries", entries);
             const char *scope_status = !lookup_ok || !generation_matches ? "coverage_unavailable"
@@ -4431,9 +5983,18 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
             yyjson_mut_obj_add_str(doc, item, "status", scope_status);
             cbm_store_free_coverage(rows, row_count);
             yyjson_mut_arr_add_val(scope_results, item);
+            scope_total += row_count;
+            scope_returned += returned;
         }
     }
     yyjson_mut_obj_add_val(doc, root, "scopes", scope_results);
+    yyjson_mut_obj_add_int(doc, root, "scope_total", scope_total);
+    yyjson_mut_obj_add_int(doc, root, "scope_returned", scope_returned);
+    yyjson_mut_obj_add_bool(doc, root, "scope_truncated", scope_returned < scope_total);
+    yyjson_mut_obj_add_bool(doc, root, "has_more", scope_offset + scope_returned < scope_total);
+    if (scope_offset + scope_returned < scope_total) {
+        yyjson_mut_obj_add_int(doc, root, "next_offset", scope_offset + scope_returned);
+    }
     yyjson_mut_obj_add_str(
         doc, root, "caveat",
         "Best-effort signal only. No recorded issue does not prove graph or source completeness; "
@@ -4442,6 +6003,7 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
     char *json = yy_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
     yyjson_doc_free(adoc);
+    free(diagnostics);
     if (have_meta) {
         cbm_store_coverage_meta_clear(&meta);
     }
@@ -4451,7 +6013,7 @@ static char *handle_check_index_coverage(cbm_mcp_server_t *srv, const char *args
         safe_str_free(&proj.root_path);
     }
     free(project);
-    char *result = cbm_mcp_text_result(json, false);
+    char *result = mcp_result_from_json(args, json);
     free(json);
     return result;
 }
@@ -4464,6 +6026,14 @@ static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
      * debugging index-location issues — gate it so the common status call
      * stays lean. */
     bool verbose = cbm_mcp_get_bool_arg(args, "verbose");
+    char *diagnostics = cbm_mcp_get_string_arg(args, "diagnostics");
+    int coverage_samples = 0;
+    if (diagnostics && strcmp(diagnostics, "summary") == 0) {
+        coverage_samples = 5;
+    } else if (diagnostics && strcmp(diagnostics, "full") == 0) {
+        coverage_samples = COVERAGE_FILE_CAP;
+    }
+    free(diagnostics);
 
     yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
     yyjson_mut_val *root = yyjson_mut_obj(doc);
@@ -4477,17 +6047,21 @@ static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
         yyjson_mut_obj_add_int(doc, root, "edges", edges);
         yyjson_mut_obj_add_str(doc, root, "status", nodes > 0 ? "ready" : "empty");
         cbm_project_t proj_info = {0};
-        if (cbm_store_get_project(store, project, &proj_info) == CBM_STORE_OK) {
+        bool have_proj_info = cbm_store_get_project(store, project, &proj_info) == CBM_STORE_OK;
+        if (have_proj_info) {
             yyjson_mut_obj_add_strcpy(doc, root, "root_path",
                                       proj_info.root_path ? proj_info.root_path : "");
+            yyjson_mut_obj_add_strcpy(doc, root, "indexed_at",
+                                      proj_info.indexed_at ? proj_info.indexed_at : "");
             if (verbose) {
                 add_git_context_json(doc, root, proj_info.root_path);
             }
-            safe_str_free(&proj_info.name);
-            safe_str_free(&proj_info.indexed_at);
-            safe_str_free(&proj_info.root_path);
         }
-        add_coverage_report(doc, root, store, project);
+        add_coverage_report(doc, root, store, project, have_proj_info ? proj_info.indexed_at : NULL,
+                            coverage_samples);
+        safe_str_free(&proj_info.name);
+        safe_str_free(&proj_info.indexed_at);
+        safe_str_free(&proj_info.root_path);
         if (nodes == 0) {
             yyjson_mut_obj_add_str(
                 doc, root, "hint",
@@ -4501,7 +6075,7 @@ static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
     yyjson_mut_doc_free(doc);
     free(project);
 
-    char *result = cbm_mcp_text_result(json, false);
+    char *result = mcp_result_from_json(args, json);
     free(json);
     return result;
 }
@@ -4875,19 +6449,19 @@ static void append_cross_repo_summary(yyjson_mut_doc *doc, yyjson_mut_val *root,
     }
 }
 
-/* Join a string list into buf with ';' separators (keeps TOON cells
- * comma-free so they need no quoting). Truncates silently at sz. */
-static void arch_join_list(char *buf, size_t sz, const char **items, int n) {
-    size_t pos = 0;
-    buf[0] = '\0';
+/* Join a complete string list with ';' separators. The caller owns the result;
+ * allocation failure is explicit rather than a partial graph identifier. */
+static char *arch_join_list(const char **items, int n) {
+    cbm_sb_t joined;
+    cbm_sb_init(&joined);
     for (int i = 0; i < n; i++) {
         const char *s = items[i] ? items[i] : "";
-        int w = snprintf(buf + pos, sz - pos, "%s%s", i > 0 ? ";" : "", s);
-        if (w < 0 || (size_t)w >= sz - pos) {
-            break;
+        if (i > 0) {
+            cbm_sb_append(&joined, ";");
         }
-        pos += (size_t)w;
+        cbm_sb_append(&joined, s);
     }
+    return cbm_sb_finish(&joined);
 }
 
 /* Compute the circular-dependency SCCs (size > 1) of the CALLS graph. Returns
@@ -5040,15 +6614,19 @@ static yyjson_mut_val *arch_json_section(yyjson_mut_doc *doc, yyjson_mut_val *ro
     return rows;
 }
 
-/* Fetch the qualified_name for a node id, or a "#<id>" fallback. */
-static void arch_node_qn(cbm_store_t *store, int64_t id, char *out, size_t outsz) {
+/* Fetch the complete qualified_name for a node id, or a "#<id>" fallback. */
+static char *arch_node_qn(cbm_store_t *store, int64_t id) {
     cbm_node_t n = {0};
+    char *out = NULL;
     if (cbm_store_find_node_by_id(store, id, &n) == CBM_STORE_OK && n.qualified_name) {
-        snprintf(out, outsz, "%s", n.qualified_name);
+        out = heap_strdup(n.qualified_name);
     } else {
-        snprintf(out, outsz, "#%lld", (long long)id);
+        char fallback[48];
+        snprintf(fallback, sizeof(fallback), "#%lld", (long long)id);
+        out = heap_strdup(fallback);
     }
     free_node_contents(&n);
+    return out;
 }
 
 static char *handle_get_architecture(cbm_mcp_server_t *srv, const char *args) {
@@ -5153,8 +6731,10 @@ static char *handle_get_architecture(cbm_mcp_server_t *srv, const char *args) {
 
     int node_count = cbm_store_count_nodes_scoped(store, project, scope_path);
     int edge_count = cbm_store_count_edges_scoped(store, project, scope_path);
-    char norm_path[CBM_SZ_512];
-    bool path_scoped = cbm_store_normalize_arch_path(scope_path, norm_path, sizeof(norm_path));
+    size_t norm_path_cap = scope_path ? strlen(scope_path) + 2U : 2U;
+    char *norm_path = malloc(norm_path_cap);
+    bool path_scoped =
+        norm_path && cbm_store_normalize_arch_path(scope_path, norm_path, norm_path_cap);
 
     /* Response encoding: tree tables by default; format:"json" emits the
      * same model as structured JSON ({cols, rows} per section). */
@@ -5308,31 +6888,56 @@ static char *handle_get_architecture(cbm_mcp_server_t *srv, const char *args) {
             cbm_tree_table_header(&sb, "clusters", arch.cluster_count, ccols, 7);
             for (int i = 0; i < arch.cluster_count; i++) {
                 const cbm_cluster_info_t *c = &arch.clusters[i];
-                char joined[CBM_SZ_1K];
                 cbm_tree_row_begin(&sb);
                 cbm_tree_cell_int(&sb, c->id, true);
                 cbm_tree_cell_str(&sb, c->label, false);
                 cbm_tree_cell_int(&sb, c->members, false);
                 cbm_tree_cell_real(&sb, c->cohesion, false);
-                arch_join_list(joined, sizeof(joined), c->top_nodes, c->top_node_count);
-                cbm_tree_cell_str(&sb, joined, false);
-                arch_join_list(joined, sizeof(joined), c->packages, c->package_count);
-                cbm_tree_cell_str(&sb, joined, false);
-                arch_join_list(joined, sizeof(joined), c->edge_types, c->edge_type_count);
-                cbm_tree_cell_str(&sb, joined, false);
+                char *top_nodes = arch_join_list(c->top_nodes, c->top_node_count);
+                char *packages = arch_join_list(c->packages, c->package_count);
+                char *edge_types = arch_join_list(c->edge_types, c->edge_type_count);
+                cbm_tree_cell_str(&sb, top_nodes ? top_nodes : "(out-of-memory)", false);
+                cbm_tree_cell_str(&sb, packages ? packages : "(out-of-memory)", false);
+                cbm_tree_cell_str(&sb, edge_types ? edge_types : "(out-of-memory)", false);
                 cbm_tree_row_end(&sb);
+                free(top_nodes);
+                free(packages);
+                free(edge_types);
             }
         }
         if (arch.file_tree_count > 0) {
             static const char *const fcols[] = {"path", "type", "children"};
-            cbm_tree_table_header(&sb, "file_tree", arch.file_tree_count, fcols, 3);
-            for (int i = 0; i < arch.file_tree_count; i++) {
-                cbm_tree_row_begin(&sb);
-                cbm_tree_cell_str(&sb, arch.file_tree[i].path, true);
-                cbm_tree_cell_str(&sb, arch.file_tree[i].type, false);
-                cbm_tree_cell_int(&sb, arch.file_tree[i].children, false);
-                cbm_tree_row_end(&sb);
+            const bool string_cols[] = {true, true, false};
+            size_t count = (size_t)arch.file_tree_count;
+            const char **cells = count <= SIZE_MAX / (3U * sizeof(*cells))
+                                     ? malloc(count * 3U * sizeof(*cells))
+                                     : NULL;
+            char (*child_values)[32] = count <= SIZE_MAX / sizeof(*child_values)
+                                           ? malloc(count * sizeof(*child_values))
+                                           : NULL;
+            if (cells && child_values) {
+                for (int i = 0; i < arch.file_tree_count; i++) {
+                    snprintf(child_values[i], sizeof(child_values[i]), "%d",
+                             arch.file_tree[i].children);
+                    cells[(size_t)i * 3U] = arch.file_tree[i].path;
+                    cells[(size_t)i * 3U + 1U] = arch.file_tree[i].type;
+                    cells[(size_t)i * 3U + 2U] = child_values[i];
+                }
+                static const bool prefix_cols[] = {true, false, false};
+                cbm_tree_table_rows_profiled(&sb, "file_tree", arch.file_tree_count, fcols, 3,
+                                             cells, string_cols, prefix_cols);
+            } else {
+                cbm_tree_table_header(&sb, "file_tree", arch.file_tree_count, fcols, 3);
+                for (int i = 0; i < arch.file_tree_count; i++) {
+                    cbm_tree_row_begin(&sb);
+                    cbm_tree_cell_str(&sb, arch.file_tree[i].path, true);
+                    cbm_tree_cell_str(&sb, arch.file_tree[i].type, false);
+                    cbm_tree_cell_int(&sb, arch.file_tree[i].children, false);
+                    cbm_tree_row_end(&sb);
+                }
             }
+            free(child_values);
+            free(cells);
         }
         /* Cross-repo edge summary (mirrors append_cross_repo_summary). */
         {
@@ -5383,20 +6988,29 @@ static char *handle_get_architecture(cbm_mcp_server_t *srv, const char *args) {
                          "cycles: %d  (rows: size members; circular CALLS dependencies)\n", ncyc);
                 cbm_sb_append(&sb, hdr);
                 for (int c = 0; c < ncyc; c++) {
-                    char row[CBM_SZ_2K];
-                    int off = snprintf(row, sizeof(row), "  %d ", sizes[c]);
                     bool clipped = sizes[c] > ARCH_SCC_MEMBERS_SHOWN;
                     int show = clipped ? ARCH_SCC_MEMBERS_SHOWN : sizes[c];
-                    for (int m = 0; m < show && off < (int)sizeof(row) - 2; m++) {
-                        char qn[CBM_SZ_512];
-                        arch_node_qn(store, members[c][m], qn, sizeof(qn));
-                        off += snprintf(row + off, sizeof(row) - off, "%s%s", m ? ";" : "", qn);
+                    cbm_sb_t member_list;
+                    cbm_sb_init(&member_list);
+                    for (int m = 0; m < show; m++) {
+                        char *qn = arch_node_qn(store, members[c][m]);
+                        if (m > 0) {
+                            cbm_sb_append(&member_list, ";");
+                        }
+                        cbm_sb_append(&member_list, qn ? qn : "(out-of-memory)");
+                        free(qn);
                     }
-                    if (clipped && off < (int)sizeof(row) - 8) {
-                        snprintf(row + off, sizeof(row) - off, ";+%d", sizes[c] - show);
+                    if (clipped) {
+                        char omitted[48];
+                        snprintf(omitted, sizeof(omitted), ";+%d", sizes[c] - show);
+                        cbm_sb_append(&member_list, omitted);
                     }
-                    cbm_sb_append(&sb, row);
-                    cbm_sb_append(&sb, "\n");
+                    char *member_text = cbm_sb_finish(&member_list);
+                    cbm_tree_row_begin(&sb);
+                    cbm_tree_cell_int(&sb, sizes[c], true);
+                    cbm_tree_cell_str(&sb, member_text ? member_text : "(out-of-memory)", false);
+                    cbm_tree_row_end(&sb);
+                    free(member_text);
                     free(members[c]);
                 }
                 free(members);
@@ -5411,6 +7025,7 @@ static char *handle_get_architecture(cbm_mcp_server_t *srv, const char *args) {
         }
         free(project);
         free(scope_path);
+        free(norm_path);
         char *text = cbm_sb_finish(&sb);
         char *result = cbm_mcp_text_result(text ? text : "out of memory", text == NULL);
         free(text);
@@ -5644,9 +7259,9 @@ static char *handle_get_architecture(cbm_mcp_server_t *srv, const char *args) {
                 yyjson_mut_val *mem = yyjson_mut_arr(doc);
                 int show = sizes[c] < ARCH_SCC_MEMBERS_SHOWN ? sizes[c] : ARCH_SCC_MEMBERS_SHOWN;
                 for (int m = 0; m < show; m++) {
-                    char qn[CBM_SZ_512];
-                    arch_node_qn(store, members[c][m], qn, sizeof(qn));
-                    yyjson_mut_arr_add_strcpy(doc, mem, qn);
+                    char *qn = arch_node_qn(store, members[c][m]);
+                    yyjson_mut_arr_add_strcpy(doc, mem, qn ? qn : "(out-of-memory)");
+                    free(qn);
                 }
                 yyjson_mut_obj_add_val(doc, o, "members", mem);
                 yyjson_mut_arr_add_val(cyc, o);
@@ -5667,6 +7282,7 @@ static char *handle_get_architecture(cbm_mcp_server_t *srv, const char *args) {
     }
     free(project);
     free(scope_path);
+    free(norm_path);
 
     char *result = cbm_mcp_text_result(json, false);
     free(json);
@@ -5734,49 +7350,113 @@ static bool is_test_file(const char *path) {
            strstr(path, "/spec/") != NULL || strstr(path, ".test.") != NULL;
 }
 
-/* Convert BFS traversal results into a yyjson_mut array. */
-/* Find the CALLS-edge "args" JSON (the serialized arg expressions) on the edge
- * that leads to the given hop node, so data_flow mode can surface argument
- * expressions (#514). Returns the borrowed substring "[...]" inside the edge's
- * properties_json, with its length, or NULL when no args are recorded. */
-static const char *bfs_edge_args_for_hop(cbm_traverse_result_t *tr, int64_t hop_node_id,
-                                         size_t *out_len) {
-    for (int e = 0; e < tr->edge_count; e++) {
-        /* The hop node is the edge endpoint reached from the root side: for an
-         * outbound trace it is the target, for inbound it is the source. Match
-         * on either so both directions surface their args. */
-        if (tr->edges[e].target_id != hop_node_id && tr->edges[e].source_id != hop_node_id) {
-            continue;
-        }
-        const char *pj = tr->edges[e].properties_json;
-        if (!pj) {
+/* Filtering belongs before page-window calculation: hidden test rows must not
+ * consume the caller's visible limit or become cursor watermarks. Compact the
+ * owned traversal array in place while preserving canonical (hop,id) order. */
+static void trace_filter_test_rows(cbm_traverse_result_t *tr) {
+    int write_index = 0;
+    for (int read_index = 0; read_index < tr->visited_count; read_index++) {
+        if (is_test_file(tr->visited[read_index].node.file_path)) {
+            cbm_node_free_fields(&tr->visited[read_index].node);
+            continue;
+        }
+        if (write_index != read_index) {
+            tr->visited[write_index] = tr->visited[read_index];
+            memset(&tr->visited[read_index], 0, sizeof(tr->visited[read_index]));
+        }
+        write_index++;
+    }
+    tr->visited_count = write_index;
+}
+
+typedef struct {
+    const cbm_traverse_result_t *full;
+    const cbm_node_t *roots;
+    int root_count;
+    bool inbound;
+} trace_edge_context_t;
+
+static bool trace_root_contains(const trace_edge_context_t *ctx, int64_t node_id) {
+    for (int i = 0; ctx && i < ctx->root_count; i++) {
+        if (ctx->roots[i].id == node_id) {
+            return true;
+        }
+    }
+    return false;
+}
+
+static int trace_hop_for_node(const trace_edge_context_t *ctx, int64_t node_id) {
+    if (!ctx || !ctx->full) {
+        return CBM_NOT_FOUND;
+    }
+    for (int i = 0; i < ctx->full->visited_count; i++) {
+        if (ctx->full->visited[i].node.id == node_id) {
+            return ctx->full->visited[i].hop;
+        }
+    }
+    return CBM_NOT_FOUND;
+}
+
+/* Edge collection returns the whole induced subgraph, not a predecessor tree.
+ * An arbitrary incident edge can therefore point sideways or away from the
+ * root. Select a deterministic edge that can actually precede this shortest-
+ * path row: it must have the traversal direction and connect hop h to h-1 (or
+ * one of the resolved roots for hop 1). */
+static const cbm_edge_info_t *trace_predecessor_edge(const trace_edge_context_t *ctx,
+                                                     const cbm_node_hop_t *hop_node) {
+    if (!ctx || !ctx->full || !hop_node || hop_node->hop <= 0) {
+        return NULL;
+    }
+    const cbm_edge_info_t *best = NULL;
+    int64_t best_predecessor = INT64_MAX;
+    for (int e = 0; e < ctx->full->edge_count; e++) {
+        const cbm_edge_info_t *edge = &ctx->full->edges[e];
+        if ((ctx->inbound && edge->source_id != hop_node->node.id) ||
+            (!ctx->inbound && edge->target_id != hop_node->node.id)) {
             continue;
         }
-        const char *args = strstr(pj, "\"args\"");
-        if (!args) {
+        int64_t predecessor = ctx->inbound ? edge->target_id : edge->source_id;
+        bool previous_hop = hop_node->hop == 1
+                                ? trace_root_contains(ctx, predecessor)
+                                : trace_hop_for_node(ctx, predecessor) == hop_node->hop - 1;
+        if (!previous_hop) {
             continue;
         }
-        const char *open = strchr(args, '[');
-        if (!open) {
-            continue;
+        const char *edge_type = edge->type ? edge->type : "";
+        const char *best_type = best && best->type ? best->type : "";
+        if (!best || predecessor < best_predecessor ||
+            (predecessor == best_predecessor && strcmp(edge_type, best_type) < 0)) {
+            best = edge;
+            best_predecessor = predecessor;
         }
-        int depth = 0;
-        const char *p = open;
-        for (; *p; p++) {
-            if (*p == '[') {
-                depth++;
-            } else if (*p == ']') {
-                depth--;
-                if (depth == 0) {
-                    p++;
-                    break;
-                }
+    }
+    return best;
+}
+
+/* Return the serialized argument-expression array from the selected canonical
+ * predecessor edge. The returned slice is borrowed from properties_json. */
+static const char *trace_edge_args(const cbm_edge_info_t *edge, size_t *out_len) {
+    const char *pj = edge ? edge->properties_json : NULL;
+    const char *args = pj ? strstr(pj, "\"args\"") : NULL;
+    const char *open = args ? strchr(args, '[') : NULL;
+    if (!open) {
+        return NULL;
+    }
+    int depth = 0;
+    const char *p = open;
+    for (; *p; p++) {
+        if (*p == '[') {
+            depth++;
+        } else if (*p == ']') {
+            depth--;
+            if (depth == 0) {
+                p++;
+                break;
             }
         }
-        *out_len = (size_t)(p - open);
-        return open;
     }
-    return NULL;
+    *out_len = (size_t)(p - open);
+    return open;
 }
 
 /* Classify a resolver strategy into the CLOSED public vocabulary.
@@ -5811,36 +7491,24 @@ const char *cbm_mcp_edge_strategy_class(const char *strategy) {
     return "heuristic";
 }
 
-/* Find the resolution evidence on the edge that leads to the given hop node —
- * the same endpoint-matching rule as bfs_edge_args_for_hop (target for an
- * outbound trace, source for inbound, so both directions surface it).
- *
- * Reads only from tr->edges, and callers pass the PAGINATED view, so evidence
- * is emitted for the rows on this page and nothing else.
- *
- * Returns false when the edge carries no strategy (non-CALLS edges do not). */
-static bool bfs_edge_evidence_for_hop(cbm_traverse_result_t *tr, int64_t hop_node_id,
-                                      const char **class_out, double *confidence_out) {
-    for (int e = 0; e < tr->edge_count; e++) {
-        if (tr->edges[e].target_id != hop_node_id && tr->edges[e].source_id != hop_node_id) {
-            continue;
-        }
-        const char *pj = tr->edges[e].properties_json;
-        if (!pj) {
-            continue;
-        }
+/* Read resolution evidence from the already-selected predecessor edge. Returns
+ * false when that edge carries no strategy (non-CALLS edges generally do not). */
+static bool trace_edge_evidence(const cbm_edge_info_t *edge, const char **class_out,
+                                double *confidence_out) {
+    const char *pj = edge ? edge->properties_json : NULL;
+    if (pj) {
         const char *key = strstr(pj, "\"strategy\"");
         if (!key) {
-            continue;
+            return false;
         }
         const char *open = strchr(key + 10, '"');
         if (!open) {
-            continue;
+            return false;
         }
         open++;
         const char *close = strchr(open, '"');
         if (!close || close == open) {
-            continue;
+            return false;
         }
         char raw[CBM_SZ_64];
         size_t len = (size_t)(close - open);
@@ -5851,7 +7519,7 @@ static bool bfs_edge_evidence_for_hop(cbm_traverse_result_t *tr, int64_t hop_nod
         raw[len] = '\0';
         const char *cls = cbm_mcp_edge_strategy_class(raw);
         if (!cls) {
-            continue;
+            return false;
         }
         *class_out = cls;
         /* Confidence rides on the same edge; absent is reported as -1 so a
@@ -5870,10 +7538,11 @@ static bool bfs_edge_evidence_for_hop(cbm_traverse_result_t *tr, int64_t hop_nod
 }
 
 /* TOON table for one trace direction: callees[N]{qn,hop,...} with optional
- * risk / test / args columns. `name` is omitted (it is the qn's last
+ * risk / test / args / evidence columns. `name` is omitted (it is the qn's last
  * segment); the per-item JSON key envelope was 84% of the legacy payload. */
 static void bfs_to_toon_table(cbm_sb_t *sb, const char *key, cbm_traverse_result_t *tr,
-                              bool risk_labels, bool include_tests, bool data_flow) {
+                              bool risk_labels, bool include_tests, bool data_flow,
+                              bool include_evidence, const trace_edge_context_t *edge_ctx) {
     int visible = 0;
     for (int i = 0; i < tr->visited_count; i++) {
         if (!include_tests && is_test_file(tr->visited[i].node.file_path)) {
@@ -5881,7 +7550,7 @@ static void bfs_to_toon_table(cbm_sb_t *sb, const char *key, cbm_traverse_result
         }
         visible++;
     }
-    const char *cols[5] = {"qn", "hop"};
+    const char *cols[7] = {"qn", "hop"};
     int ncols = 2;
     if (risk_labels) {
         cols[ncols++] = "risk";
@@ -5892,6 +7561,10 @@ static void bfs_to_toon_table(cbm_sb_t *sb, const char *key, cbm_traverse_result
     if (data_flow) {
         cols[ncols++] = "args";
     }
+    if (include_evidence) {
+        cols[ncols++] = "strategy";
+        cols[ncols++] = "confidence";
+    }
     cbm_tree_table_header(sb, key, visible, cols, ncols);
     for (int i = 0; i < tr->visited_count; i++) {
         const char *fp = tr->visited[i].node.file_path;
@@ -5908,18 +7581,35 @@ static void bfs_to_toon_table(cbm_sb_t *sb, const char *key, cbm_traverse_result
         if (include_tests) {
             cbm_tree_cell_bool(sb, test, false);
         }
+        const cbm_edge_info_t *predecessor = (data_flow || include_evidence)
+                                                 ? trace_predecessor_edge(edge_ctx, &tr->visited[i])
+                                                 : NULL;
         if (data_flow) {
             size_t alen = 0;
-            const char *ea = bfs_edge_args_for_hop(tr, tr->visited[i].node.id, &alen);
-            if (ea && alen > 0 && alen < CBM_SZ_1K) {
-                char abuf[CBM_SZ_1K];
-                memcpy(abuf, ea, alen);
-                abuf[alen] = '\0';
-                cbm_tree_cell_str(sb, abuf, false);
+            const char *ea = trace_edge_args(predecessor, &alen);
+            if (ea && alen > 0) {
+                char *args = cbm_strndup(ea, alen);
+                cbm_tree_cell_str(sb, args ? args : "", false);
+                free(args);
             } else {
                 cbm_tree_cell_str(sb, "", false);
             }
         }
+        if (include_evidence) {
+            const char *ev_class = NULL;
+            double ev_conf = -1.0;
+            if (trace_edge_evidence(predecessor, &ev_class, &ev_conf)) {
+                cbm_tree_cell_str(sb, ev_class, false);
+                if (ev_conf >= 0.0) {
+                    cbm_tree_cell_real(sb, ev_conf, false);
+                } else {
+                    cbm_tree_cell_str(sb, "-", false);
+                }
+            } else {
+                cbm_tree_cell_str(sb, "-", false);
+                cbm_tree_cell_str(sb, "-", false);
+            }
+        }
         cbm_tree_row_end(sb);
     }
 }
@@ -6032,17 +7722,25 @@ static int node_hop_cmp_hop_id(const void *pa, const void *pb) {
  * more than one graph node — e.g. a real .ts implementation plus an ambient
  * .d.ts stub, whose inbound CALLS edges are otherwise split across the two
  * nodes and silently truncated by tracing only one (#546). visited hops are
- * deduped by node id; edges are concatenated. Ownership of all heap fields
- * transfers into *out, freed by cbm_store_traverse_free. */
-static void bfs_union_same_name(cbm_store_t *store, const cbm_node_t *nodes, int node_count,
-                                const char *direction, const char **edge_types, int edge_type_count,
-                                int depth, int limit, cbm_traverse_result_t *out) {
+ * deduped by node id. Edge properties are skipped for lean traces or merged
+ * under an explicit edge_limit for data-flow/evidence output. Ownership of all
+ * heap fields transfers into *out, freed by cbm_store_traverse_free. */
+static int bfs_union_same_name(cbm_store_t *store, const cbm_node_t *nodes, int node_count,
+                               const char *direction, const char **edge_types, int edge_type_count,
+                               int depth, int limit, int edge_limit, cbm_traverse_result_t *out) {
     memset(out, 0, sizeof(*out));
     int vcap = 0, ecap = 0;
     for (int k = 0; k < node_count; k++) {
         cbm_traverse_result_t tr = {0};
-        cbm_store_bfs(store, nodes[k].id, direction, edge_types, edge_type_count, depth, limit,
-                      &tr);
+        int bfs_rc = cbm_store_bfs_with_edge_limit(store, nodes[k].id, direction, edge_types,
+                                                   edge_type_count, depth, limit, edge_limit, &tr);
+        if (bfs_rc != CBM_STORE_OK) {
+            cbm_store_traverse_free(&tr);
+            cbm_store_traverse_free(out);
+            return bfs_rc;
+        }
+        out->truncated = out->truncated || tr.truncated;
+        out->edges_truncated = out->edges_truncated || tr.edges_truncated;
         for (int i = 0; i < tr.visited_count; i++) {
             bool dup = false;
             for (int j = 0; j < out->visited_count; j++) {
@@ -6061,6 +7759,10 @@ static void bfs_union_same_name(cbm_store_t *store, const cbm_node_t *nodes, int
             if (dup) {
                 continue;
             }
+            if (out->visited_count >= limit) {
+                out->truncated = true;
+                continue;
+            }
             if (out->visited_count >= vcap) {
                 vcap = vcap ? vcap * 2 : 8;
                 out->visited = safe_realloc(out->visited, vcap * sizeof(cbm_node_hop_t));
@@ -6083,6 +7785,10 @@ static void bfs_union_same_name(cbm_store_t *store, const cbm_node_t *nodes, int
             if (edup) {
                 continue;
             }
+            if (edge_limit > 0 && out->edge_count >= edge_limit) {
+                out->edges_truncated = true;
+                continue;
+            }
             if (out->edge_count >= ecap) {
                 ecap = ecap ? ecap * 2 : 8;
                 out->edges = safe_realloc(out->edges, ecap * sizeof(cbm_edge_info_t));
@@ -6098,6 +7804,7 @@ static void bfs_union_same_name(cbm_store_t *store, const cbm_node_t *nodes, int
         qsort(out->visited, (size_t)out->visited_count, sizeof(cbm_node_hop_t),
               node_hop_cmp_hop_id);
     }
+    return CBM_STORE_OK;
 }
 
 /* ── Pagination cursors (stateless, exactly-once) ────────────────────
@@ -6130,7 +7837,9 @@ typedef struct {
 /* Hash the params that define the traversal identity. A cursor replayed with
  * different params must fail loudly, never silently mis-skip. */
 static uint64_t trace_params_hash(const char *project, const char *func_name, const char *direction,
-                                  const char *mode, int depth, bool include_tests, int limit) {
+                                  const char *mode, const char *param_name, int depth,
+                                  bool include_tests, bool risk_labels, bool include_evidence,
+                                  int limit, const char *args) {
     uint64_t h = 0xcbf29ce484222325ULL;
     h = cursor_fnv1a64(project ? project : "", h);
     h = cursor_fnv1a64("|", h);
@@ -6139,9 +7848,37 @@ static uint64_t trace_params_hash(const char *project, const char *func_name, co
     h = cursor_fnv1a64(direction ? direction : "", h);
     h = cursor_fnv1a64("|", h);
     h = cursor_fnv1a64(mode ? mode : "", h);
+    h = cursor_fnv1a64("|", h);
+    h = cursor_fnv1a64(param_name ? param_name : "", h);
     char nums[64];
-    snprintf(nums, sizeof(nums), "|%d|%d|%d", depth, include_tests ? 1 : 0, limit);
+    /* Output budget changes only how many whole rows fit after the exact
+     * watermark; it does not change graph identity. Excluding it lets a caller
+     * follow a hard-floor instruction and raise max_output_tokens without
+     * invalidating the cursor that reached that page. */
+    snprintf(nums, sizeof(nums), "|%d|%d|%d|%d|%d", depth, include_tests ? 1 : 0,
+             risk_labels ? 1 : 0, include_evidence ? 1 : 0, limit);
     h = cursor_fnv1a64(nums, h);
+
+    /* Explicit edge types define the traversed graph. Omitting them from the
+     * cursor identity allowed a token minted for CALLS to resume an IMPORTS
+     * traversal at an unrelated watermark. Preserve caller order: cursors
+     * intentionally require unchanged arguments. */
+    yyjson_doc *doc = args ? yyjson_read(args, strlen(args), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *types = root && yyjson_is_obj(root) ? yyjson_obj_get(root, "edge_types") : NULL;
+    h = cursor_fnv1a64("|edge_types=", h);
+    if (types && yyjson_is_arr(types)) {
+        size_t index;
+        size_t maximum;
+        yyjson_val *value;
+        yyjson_arr_foreach(types, index, maximum, value) {
+            h = cursor_fnv1a64(yyjson_is_str(value) ? yyjson_get_str(value) : "<non-string>", h);
+            h = cursor_fnv1a64(";", h);
+        }
+    }
+    if (doc) {
+        yyjson_doc_free(doc);
+    }
     return h;
 }
 
@@ -6158,22 +7895,49 @@ static const char *trace_cursor_decode(const char *token, const char *current_ge
         return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
     }
     const char *p = token + 3;
-    if (*p != 'o' && *p != 'i') {
+    if ((*p != 'o' && *p != 'i') || p[1] != '.') {
         return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
     }
     out->leg = *p;
     p += 2; /* leg + '.' */
     const char *gen_end = strchr(p, '.');
-    if (!gen_end || (size_t)(gen_end - p) >= sizeof(out->generation)) {
+    if (!gen_end || gen_end == p || (size_t)(gen_end - p) >= sizeof(out->generation)) {
         return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
     }
     memcpy(out->generation, p, (size_t)(gen_end - p));
     out->generation[gen_end - p] = '\0';
-    unsigned long long qh = 0;
-    long long nid = 0;
-    if (sscanf(gen_end + 1, "%16llx.%d.%lld", &qh, &out->hop, &nid) != 3) {
+    const char *hash_start = gen_end + 1;
+    const char *hash_end = strchr(hash_start, '.');
+    if (!hash_end || hash_end - hash_start != 16) {
+        return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
+    }
+    for (const char *digit = hash_start; digit < hash_end; digit++) {
+        if (!isxdigit((unsigned char)*digit)) {
+            return "invalid_cursor: unrecognized token — re-run the original query without "
+                   "'cursor'";
+        }
+    }
+    errno = 0;
+    char *parsed_end = NULL;
+    unsigned long long qh = strtoull(hash_start, &parsed_end, 16);
+    if (errno == ERANGE || parsed_end != hash_end) {
         return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
     }
+    const char *hop_start = hash_end + 1;
+    const char *hop_end = strchr(hop_start, '.');
+    errno = 0;
+    long parsed_hop = hop_end ? strtol(hop_start, &parsed_end, 10) : -1;
+    if (!hop_end || hop_end == hop_start || errno == ERANGE || parsed_end != hop_end ||
+        parsed_hop < 1 || parsed_hop > INT_MAX) {
+        return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
+    }
+    const char *node_start = hop_end + 1;
+    errno = 0;
+    long long nid = strtoll(node_start, &parsed_end, 10);
+    if (node_start == parsed_end || errno == ERANGE || *parsed_end != '\0' || nid <= 0) {
+        return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
+    }
+    out->hop = (int)parsed_hop;
     out->qhash = qh;
     out->node_id = nid;
     if (out->qhash != expected_qhash) {
@@ -6187,16 +7951,21 @@ static const char *trace_cursor_decode(const char *token, const char *current_ge
     return NULL;
 }
 
-/* Slice a canonically-ordered traversal at the watermark: index of the first
- * row strictly AFTER (hop, id). */
-static int trace_watermark_index(const cbm_traverse_result_t *tr, int hop, int64_t node_id) {
+/* Validate an exactly-issued watermark and return the first row after it.
+ * Treating an arbitrary (hop,id) as an insertion point let syntactically valid
+ * but edited cursors skip rows. The watermarked row must still exist in the
+ * selected, test-filtered leg for this generation. */
+static int trace_watermark_next_index(const cbm_traverse_result_t *tr, int hop, int64_t node_id) {
     for (int i = 0; i < tr->visited_count; i++) {
+        if (tr->visited[i].hop == hop && tr->visited[i].node.id == node_id) {
+            return i + SKIP_ONE;
+        }
         if (tr->visited[i].hop > hop ||
             (tr->visited[i].hop == hop && tr->visited[i].node.id > node_id)) {
-            return i;
+            break;
         }
     }
-    return tr->visited_count;
+    return CBM_NOT_FOUND;
 }
 
 /* json-stringified tree for one trace leg: same grouped model as the text
@@ -6204,29 +7973,33 @@ static int trace_watermark_index(const cbm_traverse_result_t *tr, int hop, int64
  * risk/args columns mirror the flags. */
 static yyjson_mut_val *bfs_to_tree_json(yyjson_mut_doc *doc, cbm_traverse_result_t *tr,
                                         bool risk_labels, bool include_tests, bool data_flow,
-                                        bool include_evidence) {
+                                        bool include_evidence,
+                                        const trace_edge_context_t *edge_ctx) {
     yyjson_mut_val *leg = yyjson_mut_obj(doc);
+    yyjson_mut_obj_add_str(doc, leg, "qn_rule",
+                           "qn = qn_prefix == \"\" ? name : qn_prefix + \".\" + name");
     yyjson_mut_val *cols = yyjson_mut_arr(doc);
     yyjson_mut_arr_add_str(doc, cols, "name");
     yyjson_mut_arr_add_str(doc, cols, "hop");
     if (risk_labels) {
         yyjson_mut_arr_add_str(doc, cols, "risk");
     }
-    /* #1542: include_evidence was implemented on the tree path only, so
-     * format:"json" silently returned cols ["name","hop"] while the schema and
-     * --help promised two more. A structured caller — the one most likely to
-     * ask for json — got no error, just missing fields. */
-    if (include_evidence) {
-        yyjson_mut_arr_add_str(doc, cols, "strategy");
-        yyjson_mut_arr_add_str(doc, cols, "confidence");
+    if (include_tests) {
+        yyjson_mut_arr_add_str(doc, cols, "test");
     }
     if (data_flow) {
         yyjson_mut_arr_add_str(doc, cols, "args");
     }
+    /* Keep declaration order identical to row emission below. Evidence is at
+     * the tail so enabling data_flow cannot put args under a strategy column. */
+    if (include_evidence) {
+        yyjson_mut_arr_add_str(doc, cols, "strategy");
+        yyjson_mut_arr_add_str(doc, cols, "confidence");
+    }
     yyjson_mut_obj_add_val(doc, leg, "cols", cols);
     yyjson_mut_val *groups = yyjson_mut_arr(doc);
     yyjson_mut_val *cur_rows = NULL;
-    char cur_group[CBM_SZ_1K] = "";
+    char *cur_group = NULL;
     bool have_group = false;
     for (int i = 0; i < tr->visited_count; i++) {
         if (!include_tests && is_test_file(tr->visited[i].node.file_path)) {
@@ -6235,11 +8008,13 @@ static yyjson_mut_val *bfs_to_tree_json(yyjson_mut_doc *doc, cbm_traverse_result
         const char *qn =
             tr->visited[i].node.qualified_name ? tr->visited[i].node.qualified_name : "";
         size_t plen = sg_qn_prefix_len(qn);
-        if (plen >= sizeof(cur_group)) {
-            plen = 0;
-        }
-        if (!have_group || strncmp(cur_group, qn, plen) != 0 || cur_group[plen] != '\0') {
-            snprintf(cur_group, sizeof(cur_group), "%.*s", (int)plen, qn);
+        if (!have_group || strlen(cur_group) != plen || memcmp(cur_group, qn, plen) != 0) {
+            char *next_group = cbm_strndup(qn, plen);
+            if (!next_group) {
+                continue;
+            }
+            free(cur_group);
+            cur_group = next_group;
             have_group = true;
             yyjson_mut_val *g = yyjson_mut_obj(doc);
             yyjson_mut_obj_add_strcpy(doc, g, "qn_prefix", cur_group);
@@ -6253,9 +8028,15 @@ static yyjson_mut_val *bfs_to_tree_json(yyjson_mut_doc *doc, cbm_traverse_result
         if (risk_labels) {
             yyjson_mut_arr_add_str(doc, row, cbm_risk_label(cbm_hop_to_risk(tr->visited[i].hop)));
         }
+        if (include_tests) {
+            yyjson_mut_arr_add_bool(doc, row, is_test_file(tr->visited[i].node.file_path));
+        }
+        const cbm_edge_info_t *predecessor = (data_flow || include_evidence)
+                                                 ? trace_predecessor_edge(edge_ctx, &tr->visited[i])
+                                                 : NULL;
         if (data_flow) {
             size_t alen = 0;
-            const char *ea = bfs_edge_args_for_hop(tr, tr->visited[i].node.id, &alen);
+            const char *ea = trace_edge_args(predecessor, &alen);
             if (ea && alen > 0) {
                 yyjson_mut_val *av = yyjson_mut_rawn(doc, ea, alen);
                 if (av) {
@@ -6270,7 +8051,7 @@ static yyjson_mut_val *bfs_to_tree_json(yyjson_mut_doc *doc, cbm_traverse_result
         if (include_evidence) {
             const char *ev_class = NULL;
             double ev_conf = -1.0;
-            if (bfs_edge_evidence_for_hop(tr, tr->visited[i].node.id, &ev_class, &ev_conf)) {
+            if (trace_edge_evidence(predecessor, &ev_class, &ev_conf)) {
                 yyjson_mut_arr_add_strcpy(doc, row, ev_class ? ev_class : "");
                 if (ev_conf >= 0.0) {
                     yyjson_mut_arr_add_real(doc, row, ev_conf);
@@ -6288,6 +8069,7 @@ static yyjson_mut_val *bfs_to_tree_json(yyjson_mut_doc *doc, cbm_traverse_result
         }
         yyjson_mut_arr_add_val(cur_rows, row);
     }
+    free(cur_group);
     yyjson_mut_obj_add_val(doc, leg, "groups", groups);
     return leg;
 }
@@ -6310,7 +8092,8 @@ static int tree_hop_cmp_qn(const void *pa, const void *pb) {
 }
 
 static void bfs_to_tree_table(cbm_sb_t *sb, const char *key, cbm_traverse_result_t *tr,
-                              bool include_tests, bool include_evidence) {
+                              bool include_tests, bool include_evidence,
+                              const trace_edge_context_t *edge_ctx) {
     int visible = 0;
     for (int i = 0; i < tr->visited_count; i++) {
         if (!include_tests && is_test_file(tr->visited[i].node.file_path)) {
@@ -6320,54 +8103,134 @@ static void bfs_to_tree_table(cbm_sb_t *sb, const char *key, cbm_traverse_result
     }
     char buf[CBM_SZ_256];
     snprintf(buf, sizeof(buf),
-             include_evidence
-                 ? "%s: %d  (rows: name hop strategy confidence; qn = group prefix + \".\" + "
-                   "name)\n"
-                 : "%s: %d  (rows: name hop; qn = group prefix + \".\" + name)\n",
-             key, visible);
+             "%s: %d  (rows: name hop%s%s; qn = group prefix empty ? "
+             "name : prefix + \".\" + name; \"\" marks empty prefix)\n",
+             key, visible, include_tests ? " test" : "",
+             include_evidence ? " strategy confidence" : "");
     cbm_sb_append(sb, buf);
-    if (tr->visited_count > 1) {
-        qsort(tr->visited, (size_t)tr->visited_count, sizeof(cbm_node_hop_t), tree_hop_cmp_qn);
-    }
-    char cur_group[CBM_SZ_1K] = "";
+    cbm_node_hop_t *ordered = visible > 0 ? malloc((size_t)visible * sizeof(*ordered)) : NULL;
+    bool ordered_owned = ordered != NULL;
+    int ordered_count = 0;
     for (int i = 0; i < tr->visited_count; i++) {
         if (!include_tests && is_test_file(tr->visited[i].node.file_path)) {
             continue;
         }
-        const char *qn =
-            tr->visited[i].node.qualified_name ? tr->visited[i].node.qualified_name : "";
-        size_t plen = sg_qn_prefix_len(qn);
-        if (plen >= sizeof(cur_group)) {
-            plen = 0;
+        if (ordered) {
+            ordered[ordered_count++] = tr->visited[i];
         }
-        if (strncmp(cur_group, qn, plen) != 0 || cur_group[plen] != '\0') {
-            snprintf(cur_group, sizeof(cur_group), "%.*s", (int)plen, qn);
-            cbm_sb_append(sb, cur_group);
+    }
+    if (!ordered && tr->visited_count > 0) {
+        /* The caller already applied the test filter; in the allocation
+         * failure path retain lossless rows in canonical order. */
+        ordered = tr->visited;
+        ordered_count = tr->visited_count;
+    }
+    if (ordered_count > 1) {
+        qsort(ordered, (size_t)ordered_count, sizeof(*ordered), tree_hop_cmp_qn);
+    }
+    char *cur_group = NULL;
+    for (int i = 0; i < ordered_count; i++) {
+        const char *qn = ordered[i].node.qualified_name ? ordered[i].node.qualified_name : "";
+        size_t plen = sg_qn_prefix_len(qn);
+        if (!cur_group || strlen(cur_group) != plen || memcmp(cur_group, qn, plen) != 0) {
+            char *next_group = cbm_strndup(qn, plen);
+            if (!next_group) {
+                continue;
+            }
+            free(cur_group);
+            cur_group = next_group;
+            cbm_sb_append(sb, cur_group[0] ? cur_group : "\"\"");
             cbm_sb_append(sb, ":\n");
         }
-        char row[CBM_SZ_512];
+        cbm_tree_row_begin(sb);
+        cbm_tree_cell_str(sb, plen ? qn + plen + 1 : qn, true);
+        cbm_tree_cell_int(sb, ordered[i].hop, false);
+        if (include_tests) {
+            cbm_tree_cell_bool(sb, is_test_file(ordered[i].node.file_path), false);
+        }
         const char *ev_class = NULL;
         double ev_conf = -1.0;
-        if (include_evidence &&
-            bfs_edge_evidence_for_hop(tr, tr->visited[i].node.id, &ev_class, &ev_conf)) {
+        const cbm_edge_info_t *predecessor =
+            include_evidence ? trace_predecessor_edge(edge_ctx, &ordered[i]) : NULL;
+        if (include_evidence && trace_edge_evidence(predecessor, &ev_class, &ev_conf)) {
+            cbm_tree_cell_str(sb, ev_class, false);
             if (ev_conf >= 0.0) {
-                snprintf(row, sizeof(row), "  %s %d %s %.2f\n", plen ? qn + plen + 1 : qn,
-                         tr->visited[i].hop, ev_class, ev_conf);
+                cbm_tree_cell_real(sb, ev_conf, false);
             } else {
-                snprintf(row, sizeof(row), "  %s %d %s -\n", plen ? qn + plen + 1 : qn,
-                         tr->visited[i].hop, ev_class);
+                cbm_tree_cell_str(sb, "-", false);
             }
         } else if (include_evidence) {
             /* The root hop has no inbound edge, and non-CALLS edges record no
              * strategy. Emit placeholders so the column count stays fixed —
              * a ragged table is worse to parse than an explicit "-". */
-            snprintf(row, sizeof(row), "  %s %d - -\n", plen ? qn + plen + 1 : qn,
-                     tr->visited[i].hop);
-        } else {
-            snprintf(row, sizeof(row), "  %s %d\n", plen ? qn + plen + 1 : qn, tr->visited[i].hop);
+            cbm_tree_cell_str(sb, "-", false);
+            cbm_tree_cell_str(sb, "-", false);
         }
-        cbm_sb_append(sb, row);
+        cbm_tree_row_end(sb);
+    }
+    free(cur_group);
+    if (ordered_owned) {
+        free(ordered);
+    }
+}
+
+/* Grouping removes repeated QN prefixes, but for singleton/scattered legs its
+ * rule and group headers cost more than a direct qn column. Both encodings are
+ * lossless, so choose the smaller serialized response instead of assuming a
+ * directory always wins. */
+static void bfs_to_adaptive_tree_table(cbm_sb_t *sb, const char *key, cbm_traverse_result_t *tr,
+                                       bool include_tests, bool include_evidence,
+                                       const trace_edge_context_t *edge_ctx) {
+    cbm_sb_t grouped;
+    cbm_sb_init(&grouped);
+    bfs_to_tree_table(&grouped, key, tr, include_tests, include_evidence, edge_ctx);
+    char *grouped_text = cbm_sb_finish(&grouped);
+
+    cbm_sb_t flat;
+    cbm_sb_init(&flat);
+    bfs_to_toon_table(&flat, key, tr, false, include_tests, false, include_evidence, edge_ctx);
+    char *flat_text = cbm_sb_finish(&flat);
+    if (flat_text && (!grouped_text || strlen(flat_text) < strlen(grouped_text))) {
+        cbm_sb_append(sb, flat_text);
+    } else if (grouped_text) {
+        cbm_sb_append(sb, grouped_text);
+    }
+    free(flat_text);
+    free(grouped_text);
+}
+
+static void trace_emit_omitted_optional_fields_tree(cbm_sb_t *sb, bool risk_labels, bool data_flow,
+                                                    bool include_evidence) {
+    char names[CBM_SZ_64] = "";
+    size_t used = 0;
+    if (risk_labels) {
+        used += (size_t)snprintf(names + used, sizeof(names) - used, "risk");
+    }
+    if (data_flow) {
+        used += (size_t)snprintf(names + used, sizeof(names) - used, "%sargs", used ? "," : "");
     }
+    if (include_evidence) {
+        (void)snprintf(names + used, sizeof(names) - used, "%sstrategy,confidence",
+                       used ? "," : "");
+    }
+    cbm_tree_scalar_str(sb, "omitted_optional_fields", names);
+}
+
+static void trace_emit_omitted_optional_fields_json(yyjson_mut_doc *doc, yyjson_mut_val *root,
+                                                    bool risk_labels, bool data_flow,
+                                                    bool include_evidence) {
+    yyjson_mut_val *names = yyjson_mut_arr(doc);
+    if (risk_labels) {
+        yyjson_mut_arr_add_str(doc, names, "risk");
+    }
+    if (data_flow) {
+        yyjson_mut_arr_add_str(doc, names, "args");
+    }
+    if (include_evidence) {
+        yyjson_mut_arr_add_str(doc, names, "strategy");
+        yyjson_mut_arr_add_str(doc, names, "confidence");
+    }
+    yyjson_mut_obj_add_val(doc, root, "omitted_optional_fields", names);
 }
 
 /* Clamp a client-supplied traversal depth to the MCP ceiling (cbm_mcp_max_depth),
@@ -6407,6 +8270,14 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
     if (trace_limit > MCP_BFS_LIMIT_MAX) {
         trace_limit = MCP_BFS_LIMIT_MAX;
     }
+    int max_output_tokens = cbm_mcp_get_int_arg(args, "max_output_tokens", 3200);
+    if (max_output_tokens < 128) {
+        max_output_tokens = 128;
+    } else if (max_output_tokens > 1000000) {
+        max_output_tokens = 1000000;
+    }
+    size_t output_budget_bytes =
+        (size_t)max_output_tokens * (size_t)MCP_OUTPUT_BYTES_PER_TOKEN_ESTIMATE;
     bool risk_labels = cbm_mcp_get_bool_arg(args, "risk_labels");
     bool include_tests = cbm_mcp_get_bool_arg(args, "include_tests");
     /* Off by default: two extra columns on every row is exactly the kind of
@@ -6470,10 +8341,9 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
             true);
     }
     if (cursor_arg && cursor_arg[0]) {
-        uint64_t qh =
-            trace_params_hash(project, func_name, direction ? direction : "both", mode,
-                              cbm_mcp_get_int_arg(args, "depth", MCP_DEFAULT_DEPTH), include_tests,
-                              cbm_mcp_get_int_arg(args, "limit", MCP_BFS_LIMIT));
+        uint64_t qh = trace_params_hash(project, func_name, direction ? direction : "both", mode,
+                                        param_name, depth, include_tests, risk_labels,
+                                        include_evidence, trace_limit, args);
         const char *cerr = trace_cursor_decode(cursor_arg, generation, qh, &cur);
         if (cerr) {
             free(cursor_arg);
@@ -6507,6 +8377,18 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
         free(param_name);
         return cbm_mcp_text_result(errbuf, true);
     }
+    if (have_cursor && ((cur.leg == 'o' && strcmp(direction, "inbound") == 0) ||
+                        (cur.leg == 'i' && strcmp(direction, "outbound") == 0))) {
+        free(func_name);
+        free(project);
+        free(direction);
+        free(mode);
+        free(param_name);
+        return cbm_mcp_text_result(
+            "invalid_cursor: cursor leg is incompatible with the requested direction — "
+            "re-run the original query without 'cursor'",
+            true);
+    }
 
     /* Find the node by name. If the bare-name lookup misses, fall back to
      * qualified_name so callers passing a fully-qualified identifier (which
@@ -6532,20 +8414,25 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
     }
 
     if (node_count == 0) {
-        enum { HINT_BUF_SZ = 512 };
-        char hint[HINT_BUF_SZ];
-        snprintf(hint, sizeof(hint),
-                 "{\"error\":\"function not found\",\"function_name\":\"%s\","
-                 "\"hint\":\"Use search_graph(name_pattern=\\\".*%s.*\\\") to find the exact "
-                 "name, then pass it to trace_path.\"}",
-                 func_name, func_name);
+        yyjson_mut_doc *error_doc = yyjson_mut_doc_new(NULL);
+        yyjson_mut_val *error_obj = yyjson_mut_obj(error_doc);
+        yyjson_mut_doc_set_root(error_doc, error_obj);
+        yyjson_mut_obj_add_str(error_doc, error_obj, "error", "function not found");
+        yyjson_mut_obj_add_strcpy(error_doc, error_obj, "function_name", func_name);
+        yyjson_mut_obj_add_str(error_doc, error_obj, "hint",
+                               "Use search_graph(name_pattern=...) to find the exact qualified "
+                               "name, then pass it to trace_path.");
+        char *error_json = yy_doc_to_str(error_doc);
+        yyjson_mut_doc_free(error_doc);
         free(func_name);
         free(project);
         free(direction);
         free(mode);
         free(param_name);
         cbm_store_free_nodes(nodes, 0);
-        return cbm_mcp_text_result(hint, true);
+        char *result = cbm_mcp_text_result(error_json ? error_json : "function not found", true);
+        free(error_json);
+        return result;
     }
 
     /* Disambiguate same-named matches: prefer the real definition, and report
@@ -6585,6 +8472,8 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
     cbm_traverse_result_t tr_in = {0};
 
     bool data_flow = mode && strcmp(mode, "data_flow") == 0;
+    bool need_edge_data = data_flow || include_evidence;
+    int edge_data_limit = need_edge_data ? MCP_BFS_LIMIT_MAX : 0;
 
     (void)sel; /* union across all same-name nodes — see bfs_union_same_name (#546) */
 
@@ -6593,13 +8482,34 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
      * materializing up to MCP_BFS_LIMIT_MAX rows costs the same traversal —
      * and gives exact totals plus the rows every later page needs. The page
      * size (trace_limit) only bounds what THIS response emits. */
+    int traversal_rc = CBM_STORE_OK;
     if (do_outbound) {
-        bfs_union_same_name(store, nodes, node_count, "outbound", edge_types, edge_type_count,
-                            depth, MCP_BFS_LIMIT_MAX, &tr_out);
+        traversal_rc =
+            bfs_union_same_name(store, nodes, node_count, "outbound", edge_types, edge_type_count,
+                                depth, MCP_BFS_LIMIT_MAX, edge_data_limit, &tr_out);
     }
-    if (do_inbound) {
-        bfs_union_same_name(store, nodes, node_count, "inbound", edge_types, edge_type_count, depth,
-                            MCP_BFS_LIMIT_MAX, &tr_in);
+    if (traversal_rc == CBM_STORE_OK && do_inbound) {
+        traversal_rc =
+            bfs_union_same_name(store, nodes, node_count, "inbound", edge_types, edge_type_count,
+                                depth, MCP_BFS_LIMIT_MAX, edge_data_limit, &tr_in);
+    }
+    if (traversal_rc != CBM_STORE_OK) {
+        cbm_store_traverse_free(&tr_out);
+        cbm_store_traverse_free(&tr_in);
+        cbm_store_free_nodes(nodes, node_count);
+        free(func_name);
+        free(project);
+        free(direction);
+        free(mode);
+        free(param_name);
+        if (et_doc_keep) {
+            yyjson_doc_free(et_doc_keep);
+        }
+        return cbm_mcp_text_result("trace traversal failed; inspect index_status and retry", true);
+    }
+    if (!include_tests) {
+        trace_filter_test_rows(&tr_out);
+        trace_filter_test_rows(&tr_in);
     }
 
     /* Page windows in canonical (hop,id) order. Legs drain in a fixed order
@@ -6609,11 +8519,31 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
     int out_start = 0;
     int in_start = 0;
     if (have_cursor) {
+        int watermark_next = CBM_NOT_FOUND;
         if (cur.leg == 'o') {
-            out_start = trace_watermark_index(&tr_out, cur.hop, cur.node_id);
+            watermark_next = trace_watermark_next_index(&tr_out, cur.hop, cur.node_id);
+            out_start = watermark_next;
         } else {
             out_start = tr_out.visited_count; /* callees leg already drained */
-            in_start = trace_watermark_index(&tr_in, cur.hop, cur.node_id);
+            watermark_next = trace_watermark_next_index(&tr_in, cur.hop, cur.node_id);
+            in_start = watermark_next;
+        }
+        if (watermark_next == CBM_NOT_FOUND) {
+            cbm_store_traverse_free(&tr_out);
+            cbm_store_traverse_free(&tr_in);
+            cbm_store_free_nodes(nodes, node_count);
+            free(func_name);
+            free(project);
+            free(direction);
+            free(mode);
+            free(param_name);
+            if (et_doc_keep) {
+                yyjson_doc_free(et_doc_keep);
+            }
+            return cbm_mcp_text_result(
+                "invalid_cursor: watermark is not present in the selected visible trace leg — "
+                "re-run the original query without 'cursor'",
+                true);
         }
     }
     int budget = trace_limit;
@@ -6632,27 +8562,55 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
             in_len = budget;
         }
     }
+    const int requested_out_len = out_len;
+    const int requested_in_len = in_len;
+    const int requested_page_rows = requested_out_len + requested_in_len;
+    int row_target = requested_page_rows;
+    int budget_search_low = 0;
+    int budget_search_high = requested_page_rows;
+    int budget_search_best = 0;
+    bool budget_search_active = false;
+    bool output_budget_hit = false;
+    bool emit_optional_fields = risk_labels || data_flow || include_evidence;
+    bool optional_fields_omitted = false;
+    char *json = NULL;
+
+render_trace_output:;
+    int rows_left = row_target;
+    out_len = requested_out_len < rows_left ? requested_out_len : rows_left;
+    rows_left -= out_len;
+    in_len = requested_in_len < rows_left ? requested_in_len : rows_left;
     bool out_more = do_outbound && out_start + out_len < tr_out.visited_count;
     bool in_more = do_inbound && in_start + in_len < tr_in.visited_count;
     bool more_rows = out_more || in_more;
+    bool engine_saturated = tr_out.truncated || tr_in.truncated;
+    bool edge_data_saturated = tr_out.edges_truncated || tr_in.edges_truncated;
+    bool trace_truncated =
+        more_rows || engine_saturated || edge_data_saturated || output_budget_hit;
     char next_tok[192] = "";
     /* Never mint a cursor under a "legacy" generation (no staleness
      * detection); the truncated flag + raise-limit hint still fire below. */
     if (more_rows && !gen_legacy) {
         trace_cursor_t nc = {0};
         snprintf(nc.generation, sizeof(nc.generation), "%s", generation);
-        nc.qhash = trace_params_hash(project, func_name, direction, mode, depth, include_tests,
-                                     trace_limit);
-        if (out_more) {
-            nc.leg = 'o';
-            nc.hop = tr_out.visited[out_start + out_len - 1].hop;
-            nc.node_id = tr_out.visited[out_start + out_len - 1].node.id;
-        } else {
+        nc.qhash =
+            trace_params_hash(project, func_name, direction, mode, param_name, depth, include_tests,
+                              risk_labels, include_evidence, trace_limit, args);
+        /* The watermark is the last row ACTUALLY emitted, not the leg that
+         * happens to have additional rows. At an exact outbound page boundary
+         * inbound may be pending with zero emitted rows. */
+        if (in_len > 0) {
             nc.leg = 'i';
             nc.hop = tr_in.visited[in_start + in_len - 1].hop;
             nc.node_id = tr_in.visited[in_start + in_len - 1].node.id;
+        } else if (out_len > 0) {
+            nc.leg = 'o';
+            nc.hop = tr_out.visited[out_start + out_len - 1].hop;
+            nc.node_id = tr_out.visited[out_start + out_len - 1].node.id;
+        }
+        if (in_len > 0 || out_len > 0) {
+            trace_cursor_encode(&nc, next_tok, sizeof(next_tok));
         }
-        trace_cursor_encode(&nc, next_tok, sizeof(next_tok));
     }
 
     /* Window views: visited offset + count; the full edges array stays
@@ -6664,6 +8622,10 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
     cbm_traverse_result_t view_in = tr_in;
     view_in.visited = tr_in.visited ? tr_in.visited + in_start : NULL;
     view_in.visited_count = in_len;
+    trace_edge_context_t out_edge_ctx = {
+        .full = &tr_out, .roots = nodes, .root_count = node_count, .inbound = false};
+    trace_edge_context_t in_edge_ctx = {
+        .full = &tr_in, .roots = nodes, .root_count = node_count, .inbound = true};
 
     /* Totals must count what the caller can actually enumerate: when
      * include_tests=false the tables hide test-file rows, so raw
@@ -6683,7 +8645,8 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
         }
     }
 
-    char *json = NULL;
+    free(json);
+    json = NULL;
     if (!trace_legacy_json) {
         cbm_sb_t sb;
         cbm_sb_init(&sb);
@@ -6694,35 +8657,74 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
         }
         /* Grouped tree is THE default; risk_labels/data_flow keep the flat
          * table (extra columns) in the same tree syntax. */
-        bool flat_trace = risk_labels || data_flow;
+        bool render_risk = risk_labels && emit_optional_fields;
+        bool render_data_flow = data_flow && emit_optional_fields;
+        bool render_evidence = include_evidence && emit_optional_fields;
+        bool flat_trace = render_risk || render_data_flow;
         if (do_outbound) {
             cbm_tree_scalar_int(&sb, "callees_total", out_total);
+            cbm_tree_scalar_str(&sb, "callees_total_relation", tr_out.truncated ? "gte" : "eq");
             if (flat_trace) {
-                bfs_to_toon_table(&sb, "callees", &view_out, risk_labels, include_tests, data_flow);
+                bfs_to_toon_table(&sb, "callees", &view_out, render_risk, include_tests,
+                                  render_data_flow, render_evidence, &out_edge_ctx);
             } else {
-                bfs_to_tree_table(&sb, "callees", &view_out, include_tests, include_evidence);
+                bfs_to_adaptive_tree_table(&sb, "callees", &view_out, include_tests,
+                                           render_evidence, &out_edge_ctx);
             }
         }
         if (do_inbound) {
             cbm_tree_scalar_int(&sb, "callers_total", in_total);
+            cbm_tree_scalar_str(&sb, "callers_total_relation", tr_in.truncated ? "gte" : "eq");
             if (flat_trace) {
-                bfs_to_toon_table(&sb, "callers", &view_in, risk_labels, include_tests, data_flow);
+                bfs_to_toon_table(&sb, "callers", &view_in, render_risk, include_tests,
+                                  render_data_flow, render_evidence, &in_edge_ctx);
             } else {
-                bfs_to_tree_table(&sb, "callers", &view_in, include_tests, include_evidence);
+                bfs_to_adaptive_tree_table(&sb, "callers", &view_in, include_tests, render_evidence,
+                                           &in_edge_ctx);
             }
         }
-        if (more_rows) {
+        if (trace_truncated) {
             cbm_tree_scalar_bool(&sb, "truncated", true);
+            cbm_tree_scalar_bool(&sb, "has_more", more_rows);
+            cbm_tree_scalar_str(
+                &sb, "truncation_reason",
+                output_budget_hit
+                    ? "output_budget"
+                    : (more_rows ? "page_limit"
+                                 : (engine_saturated ? "engine_limit" : "edge_data_limit")));
+            if (output_budget_hit) {
+                cbm_tree_scalar_int(&sb, "max_output_bytes", (long long)output_budget_bytes);
+            }
+            if (optional_fields_omitted) {
+                cbm_tree_scalar_bool(&sb, "optional_fields_omitted", true);
+                trace_emit_omitted_optional_fields_tree(&sb, risk_labels, data_flow,
+                                                        include_evidence);
+            }
+            if (engine_saturated) {
+                cbm_tree_scalar_bool(&sb, "engine_saturated", true);
+            }
+            if (edge_data_saturated) {
+                cbm_tree_scalar_bool(&sb, "edge_data_saturated", true);
+            }
             if (next_tok[0]) {
                 cbm_tree_scalar_str(&sb, "next", next_tok);
                 cbm_tree_scalar_str(&sb, "hint",
                                     "more rows exist — re-call with cursor set to 'next' and ALL "
                                     "other arguments identical (no duplicates), or narrow with "
                                     "depth/edge_types");
-            } else {
+            } else if (more_rows) {
                 cbm_tree_scalar_str(&sb, "hint",
                                     "more rows exist — re-call with a higher 'limit' (cursors "
                                     "unavailable: index predates generation tracking)");
+            } else if (engine_saturated) {
+                cbm_tree_scalar_str(
+                    &sb, "hint",
+                    "Traversal reached the 5000-node safety ceiling; narrow depth/edge_types "
+                    "or use query_graph for a differently bounded traversal.");
+            } else {
+                cbm_tree_scalar_str(&sb, "hint",
+                                    "Optional edge evidence reached its 5000-edge ceiling; narrow "
+                                    "depth/edge_types or disable data_flow/include_evidence.");
             }
         }
         json = cbm_sb_finish(&sb);
@@ -6738,18 +8740,47 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
         }
         if (do_outbound) {
             yyjson_mut_obj_add_int(doc, root, "callees_total", out_total);
-            yyjson_mut_obj_add_val(doc, root, "callees",
-                                   bfs_to_tree_json(doc, &view_out, risk_labels, include_tests,
-                                                    data_flow, include_evidence));
+            yyjson_mut_obj_add_str(doc, root, "callees_total_relation",
+                                   tr_out.truncated ? "gte" : "eq");
+            yyjson_mut_obj_add_val(
+                doc, root, "callees",
+                bfs_to_tree_json(doc, &view_out, risk_labels && emit_optional_fields, include_tests,
+                                 data_flow && emit_optional_fields,
+                                 include_evidence && emit_optional_fields, &out_edge_ctx));
         }
         if (do_inbound) {
             yyjson_mut_obj_add_int(doc, root, "callers_total", in_total);
-            yyjson_mut_obj_add_val(doc, root, "callers",
-                                   bfs_to_tree_json(doc, &view_in, risk_labels, include_tests,
-                                                    data_flow, include_evidence));
-        }
-        if (more_rows) {
+            yyjson_mut_obj_add_str(doc, root, "callers_total_relation",
+                                   tr_in.truncated ? "gte" : "eq");
+            yyjson_mut_obj_add_val(
+                doc, root, "callers",
+                bfs_to_tree_json(doc, &view_in, risk_labels && emit_optional_fields, include_tests,
+                                 data_flow && emit_optional_fields,
+                                 include_evidence && emit_optional_fields, &in_edge_ctx));
+        }
+        if (trace_truncated) {
             yyjson_mut_obj_add_bool(doc, root, "truncated", true);
+            yyjson_mut_obj_add_bool(doc, root, "has_more", more_rows);
+            yyjson_mut_obj_add_str(
+                doc, root, "truncation_reason",
+                output_budget_hit
+                    ? "output_budget"
+                    : (more_rows ? "page_limit"
+                                 : (engine_saturated ? "engine_limit" : "edge_data_limit")));
+            if (output_budget_hit) {
+                yyjson_mut_obj_add_uint(doc, root, "max_output_bytes", output_budget_bytes);
+            }
+            if (optional_fields_omitted) {
+                yyjson_mut_obj_add_bool(doc, root, "optional_fields_omitted", true);
+                trace_emit_omitted_optional_fields_json(doc, root, risk_labels, data_flow,
+                                                        include_evidence);
+            }
+            if (engine_saturated) {
+                yyjson_mut_obj_add_bool(doc, root, "engine_saturated", true);
+            }
+            if (edge_data_saturated) {
+                yyjson_mut_obj_add_bool(doc, root, "edge_data_saturated", true);
+            }
             if (next_tok[0]) {
                 yyjson_mut_obj_add_strcpy(doc, root, "next_cursor", next_tok);
             }
@@ -6759,6 +8790,114 @@ static char *handle_trace_call_path(cbm_mcp_server_t *srv, const char *args) {
         yyjson_mut_doc_free(doc);
     }
 
+    /* Apply the deterministic byte ceiling after serialization. Optional
+     * diagnostics yield first; if primary graph rows still do not fit, find
+     * the largest whole-row prefix. Cursor watermarks are recomputed on every
+     * render, so `next` always follows the last row actually emitted. */
+    if (json && strlen(json) > output_budget_bytes) {
+        output_budget_hit = true;
+        if (emit_optional_fields) {
+            emit_optional_fields = false;
+            optional_fields_omitted = true;
+            goto render_trace_output;
+        }
+        if (row_target <= 1 || requested_page_rows == 0) {
+            free(json);
+            bool floor_has_more = requested_page_rows > 0;
+            if (!trace_legacy_json) {
+                cbm_sb_t floor;
+                cbm_sb_init(&floor);
+                if (do_outbound) {
+                    cbm_tree_scalar_int(&floor, "callees_total", out_total);
+                    cbm_tree_scalar_str(&floor, "callees_total_relation",
+                                        tr_out.truncated ? "gte" : "eq");
+                }
+                if (do_inbound) {
+                    cbm_tree_scalar_int(&floor, "callers_total", in_total);
+                    cbm_tree_scalar_str(&floor, "callers_total_relation",
+                                        tr_in.truncated ? "gte" : "eq");
+                }
+                cbm_tree_scalar_bool(&floor, "has_more", floor_has_more);
+                if (floor_has_more) {
+                    cbm_tree_scalar_bool(&floor, "continuation_requires_higher_budget", true);
+                }
+                cbm_tree_scalar_bool(&floor, "truncated", true);
+                cbm_tree_scalar_str(&floor, "truncation_reason", "output_budget");
+                cbm_tree_scalar_bool(&floor, "output_budget_floor_exceeded", true);
+                cbm_tree_scalar_int(&floor, "max_output_bytes", (long long)output_budget_bytes);
+                if (optional_fields_omitted) {
+                    cbm_tree_scalar_bool(&floor, "optional_fields_omitted", true);
+                    trace_emit_omitted_optional_fields_tree(&floor, risk_labels, data_flow,
+                                                            include_evidence);
+                }
+                cbm_tree_scalar_str(&floor, "hint",
+                                    "raise max_output_tokens; no identifier was sliced");
+                json = cbm_sb_finish(&floor);
+            } else {
+                yyjson_mut_doc *floor_doc = yyjson_mut_doc_new(NULL);
+                yyjson_mut_val *floor = yyjson_mut_obj(floor_doc);
+                yyjson_mut_doc_set_root(floor_doc, floor);
+                if (do_outbound) {
+                    yyjson_mut_obj_add_int(floor_doc, floor, "callees_total", out_total);
+                    yyjson_mut_obj_add_str(floor_doc, floor, "callees_total_relation",
+                                           tr_out.truncated ? "gte" : "eq");
+                }
+                if (do_inbound) {
+                    yyjson_mut_obj_add_int(floor_doc, floor, "callers_total", in_total);
+                    yyjson_mut_obj_add_str(floor_doc, floor, "callers_total_relation",
+                                           tr_in.truncated ? "gte" : "eq");
+                }
+                yyjson_mut_obj_add_bool(floor_doc, floor, "has_more", floor_has_more);
+                if (floor_has_more) {
+                    yyjson_mut_obj_add_bool(floor_doc, floor, "continuation_requires_higher_budget",
+                                            true);
+                }
+                yyjson_mut_obj_add_bool(floor_doc, floor, "truncated", true);
+                yyjson_mut_obj_add_str(floor_doc, floor, "truncation_reason", "output_budget");
+                yyjson_mut_obj_add_bool(floor_doc, floor, "output_budget_floor_exceeded", true);
+                yyjson_mut_obj_add_uint(floor_doc, floor, "max_output_bytes", output_budget_bytes);
+                if (optional_fields_omitted) {
+                    yyjson_mut_obj_add_bool(floor_doc, floor, "optional_fields_omitted", true);
+                    trace_emit_omitted_optional_fields_json(floor_doc, floor, risk_labels,
+                                                            data_flow, include_evidence);
+                }
+                yyjson_mut_obj_add_str(floor_doc, floor, "hint",
+                                       "raise max_output_tokens; no identifier was sliced");
+                json = yy_doc_to_str(floor_doc);
+                yyjson_mut_doc_free(floor_doc);
+            }
+            goto trace_output_ready;
+        }
+        if (!budget_search_active) {
+            budget_search_active = true;
+            budget_search_low = 1;
+            budget_search_high = row_target - 1;
+        } else {
+            budget_search_high = row_target - 1;
+        }
+        if (budget_search_low > budget_search_high) {
+            if (budget_search_best < 1) {
+                row_target = 1;
+            } else {
+                row_target = budget_search_best;
+            }
+            budget_search_active = false;
+            goto render_trace_output;
+        }
+        row_target = budget_search_low + (budget_search_high - budget_search_low) / 2;
+        goto render_trace_output;
+    }
+    if (budget_search_active) {
+        budget_search_best = row_target;
+        budget_search_low = row_target + 1;
+        if (budget_search_low <= budget_search_high) {
+            row_target = budget_search_low + (budget_search_high - budget_search_low + 1) / 2;
+            goto render_trace_output;
+        }
+    }
+
+trace_output_ready:
+
     /* Now safe to free traversal data */
     if (do_outbound) {
         cbm_store_traverse_free(&tr_out);
@@ -6802,37 +8941,30 @@ static char *read_file_lines(const char *path, int start, int end) {
         return NULL;
     }
 
-    size_t cap = CBM_SZ_4K;
-    char *buf = malloc(cap);
-    size_t len = 0;
-    buf[0] = '\0';
-
-    char line[CBM_SZ_2K];
-    int lineno = 0;
-    while (fgets(line, sizeof(line), fp)) {
-        lineno++;
-        if (lineno < start) {
-            continue;
-        }
-        if (lineno > end) {
-            break;
+    cbm_sb_t selected;
+    cbm_sb_init(&selected);
+    int lineno = 1;
+    int byte;
+    while ((byte = fgetc(fp)) != EOF) {
+        if (lineno >= start && lineno <= end) {
+            char ch = (char)byte;
+            cbm_sb_append_n(&selected, &ch, 1U);
         }
-        size_t ll = strlen(line);
-        while (len + ll + SKIP_ONE > cap) {
-            cap *= PAIR_LEN;
-            buf = safe_realloc(buf, cap);
+        if (byte == '\n') {
+            if (lineno >= end) {
+                break;
+            }
+            lineno++;
         }
-        memcpy(buf + len, line, ll);
-        len += ll;
-        buf[len] = '\0';
     }
 
     (void)fclose(fp);
-    if (len == 0) {
-        free(buf);
+    char *result = cbm_sb_finish(&selected);
+    if (result && result[0] == '\0') {
+        free(result);
         return NULL;
     }
-    return buf;
+    return result;
 }
 
 /* ── Helper: get project root_path from store ─────────────────── */
@@ -8355,13 +10487,44 @@ static bool utf8_is_cont(unsigned char c) {
     return (c & 0xC0) == 0x80;
 }
 
+static size_t utf8_sequence_len(const unsigned char *p, const unsigned char *end) {
+    size_t remaining = (size_t)(end - p);
+    unsigned char c = *p;
+    if (c < 0x80) {
+        return 1;
+    }
+    if (c >= 0xC2 && c <= 0xDF && remaining >= 2 && utf8_is_cont(p[1])) {
+        return 2;
+    }
+    if (c == 0xE0 && remaining >= 3 && p[1] >= 0xA0 && p[1] <= 0xBF && utf8_is_cont(p[2])) {
+        return 3;
+    }
+    if (c >= 0xE1 && c <= 0xEC && remaining >= 3 && utf8_is_cont(p[1]) && utf8_is_cont(p[2])) {
+        return 3;
+    }
+    if (c == 0xED && remaining >= 3 && p[1] >= 0x80 && p[1] <= 0x9F && utf8_is_cont(p[2])) {
+        return 3;
+    }
+    if (c >= 0xEE && c <= 0xEF && remaining >= 3 && utf8_is_cont(p[1]) && utf8_is_cont(p[2])) {
+        return 3;
+    }
+    if (c == 0xF0 && remaining >= 4 && p[1] >= 0x90 && p[1] <= 0xBF && utf8_is_cont(p[2]) &&
+        utf8_is_cont(p[3])) {
+        return 4;
+    }
+    if (c >= 0xF1 && c <= 0xF3 && remaining >= 4 && utf8_is_cont(p[1]) && utf8_is_cont(p[2]) &&
+        utf8_is_cont(p[3])) {
+        return 4;
+    }
+    if (c == 0xF4 && remaining >= 4 && p[1] >= 0x80 && p[1] <= 0x8F && utf8_is_cont(p[2]) &&
+        utf8_is_cont(p[3])) {
+        return 4;
+    }
+    return 0;
+}
+
 static char *sanitize_utf8_lossy(const char *s) {
-    enum {
-        UTF8_REPLACEMENT_LEN = 3,
-        UTF8_THREE_BYTE_LEN = 3,
-        UTF8_FOUR_BYTE_LEN = 4,
-        UTF8_FOURTH_BYTE = 3,
-    };
+    enum { UTF8_REPLACEMENT_LEN = 3 };
     if (!s) {
         return NULL;
     }
@@ -8378,32 +10541,7 @@ static char *sanitize_utf8_lossy(const char *s) {
     const unsigned char *end = p + len;
     unsigned char *dst = (unsigned char *)out;
     while (p < end) {
-        unsigned char c = *p;
-        size_t n = 0;
-        if (c < 0x80) {
-            n = 1;
-        } else if (c >= 0xC2 && c <= 0xDF && p + 1 < end && utf8_is_cont(p[1])) {
-            n = 2;
-        } else if (c == 0xE0 && p + 2 < end && p[1] >= 0xA0 && p[1] <= 0xBF && utf8_is_cont(p[2])) {
-            n = UTF8_THREE_BYTE_LEN;
-        } else if (c >= 0xE1 && c <= 0xEC && p + 2 < end && utf8_is_cont(p[1]) &&
-                   utf8_is_cont(p[2])) {
-            n = UTF8_THREE_BYTE_LEN;
-        } else if (c == 0xED && p + 2 < end && p[1] >= 0x80 && p[1] <= 0x9F && utf8_is_cont(p[2])) {
-            n = UTF8_THREE_BYTE_LEN;
-        } else if (c >= 0xEE && c <= 0xEF && p + 2 < end && utf8_is_cont(p[1]) &&
-                   utf8_is_cont(p[2])) {
-            n = UTF8_THREE_BYTE_LEN;
-        } else if (c == 0xF0 && p + UTF8_FOURTH_BYTE < end && p[1] >= 0x90 && p[1] <= 0xBF &&
-                   utf8_is_cont(p[2]) && utf8_is_cont(p[UTF8_FOURTH_BYTE])) {
-            n = UTF8_FOUR_BYTE_LEN;
-        } else if (c >= 0xF1 && c <= 0xF3 && p + UTF8_FOURTH_BYTE < end && utf8_is_cont(p[1]) &&
-                   utf8_is_cont(p[2]) && utf8_is_cont(p[UTF8_FOURTH_BYTE])) {
-            n = UTF8_FOUR_BYTE_LEN;
-        } else if (c == 0xF4 && p + UTF8_FOURTH_BYTE < end && p[1] >= 0x80 && p[1] <= 0x8F &&
-                   utf8_is_cont(p[2]) && utf8_is_cont(p[UTF8_FOURTH_BYTE])) {
-            n = UTF8_FOUR_BYTE_LEN;
-        }
+        size_t n = utf8_sequence_len(p, end);
 
         if (n > 0) {
             memcpy(dst, p, n);
@@ -8420,6 +10558,26 @@ static char *sanitize_utf8_lossy(const char *s) {
     return out;
 }
 
+/* Fixed-width search buffers cannot grow invalid bytes into the three-byte
+ * replacement character. Preserve every valid UTF-8 sequence and replace an
+ * invalid byte in place with '?', keeping the result valid without losing
+ * non-ASCII identifiers, paths, comments, or source text. */
+static void sanitize_utf8_inplace(char *s) {
+    if (!s) {
+        return;
+    }
+    unsigned char *p = (unsigned char *)s;
+    const unsigned char *end = p + strlen(s);
+    while (p < end) {
+        size_t n = utf8_sequence_len(p, end);
+        if (n > 0) {
+            p += n;
+        } else {
+            *p++ = '?';
+        }
+    }
+}
+
 /* Build an enriched snippet response for a resolved node. */
 /* Add a string array to a JSON object (no-op if count == 0). */
 static void add_string_array(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key,
@@ -8444,48 +10602,232 @@ static void add_snippet_coverage_note(yyjson_mut_doc *doc, yyjson_mut_val *root_
     if (!node->file_path || !node->file_path[0] || !node->project) {
         return;
     }
-    cbm_coverage_row_t *rows = NULL;
-    int count = 0;
-    if (cbm_store_coverage_get_path(store, node->project, node->file_path, &rows, &count) !=
-        CBM_STORE_OK) {
-        return;
+    cbm_coverage_row_t *rows = NULL;
+    int count = 0;
+    if (cbm_store_coverage_get_path(store, node->project, node->file_path, &rows, &count) !=
+        CBM_STORE_OK) {
+        return;
+    }
+    for (int i = 0; i < count; i++) {
+        if (rows[i].rel_path && strcmp(rows[i].rel_path, node->file_path) == 0 && rows[i].kind &&
+            strcmp(rows[i].kind, "parse_partial") == 0) {
+            char note[CBM_SZ_1K];
+            snprintf(note, sizeof(note),
+                     "This file was only PARTIALLY indexed — line range(s) %s could not be "
+                     "parsed, so constructs there may be missing from the graph (callers/callees "
+                     "and search results can under-report this file). The source above is ground "
+                     "truth. (best-effort signal)",
+                     rows[i].detail && rows[i].detail[0] ? rows[i].detail : "?");
+            yyjson_mut_obj_add_strcpy(doc, root_obj, "coverage_note", note);
+            break;
+        }
+    }
+    cbm_store_free_coverage(rows, count);
+}
+
+static int snippet_member_cmp(const void *left, const void *right) {
+    const cbm_node_t *a = left;
+    const cbm_node_t *b = right;
+    if (a->start_line != b->start_line) {
+        return a->start_line < b->start_line ? -1 : 1;
+    }
+    if (a->end_line != b->end_line) {
+        return a->end_line < b->end_line ? -1 : 1;
+    }
+    int qn_cmp = strcmp(a->qualified_name ? a->qualified_name : "",
+                        b->qualified_name ? b->qualified_name : "");
+    if (qn_cmp != 0) {
+        return qn_cmp;
+    }
+    return a->id < b->id ? -1 : a->id > b->id ? 1 : 0;
+}
+
+static void snippet_obj_set_int(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key,
+                                int value) {
+    (void)yyjson_mut_obj_remove_key(obj, key);
+    yyjson_mut_obj_add_int(doc, obj, key, value);
+}
+
+static void snippet_obj_set_bool(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key,
+                                 bool value) {
+    (void)yyjson_mut_obj_remove_key(obj, key);
+    yyjson_mut_obj_add_bool(doc, obj, key, value);
+}
+
+static char *snippet_render_payload(yyjson_mut_doc *doc, const char *args) {
+    char *json = yy_doc_to_str(doc);
+    if (!json || mcp_wants_json(args)) {
+        return json;
+    }
+    char *tree = cbm_json_to_tree(json);
+    free(json);
+    return tree;
+}
+
+static int snippet_source_line_count(const char *source) {
+    if (!source || !source[0]) {
+        return 0;
+    }
+    int lines = 1;
+    for (const char *p = source; *p; p++) {
+        if (*p == '\n' && p[1] != '\0') {
+            lines++;
+        }
+    }
+    return lines;
+}
+
+/* Copy at most `line_limit` complete physical lines. A single over-budget
+ * line therefore yields no source instead of a corrupt byte prefix. */
+static char *snippet_source_line_prefix(const char *source, int line_limit) {
+    if (!source || line_limit <= 0) {
+        return NULL;
     }
-    for (int i = 0; i < count; i++) {
-        if (rows[i].rel_path && strcmp(rows[i].rel_path, node->file_path) == 0 && rows[i].kind &&
-            strcmp(rows[i].kind, "parse_partial") == 0) {
-            char note[CBM_SZ_1K];
-            snprintf(note, sizeof(note),
-                     "This file was only PARTIALLY indexed — line range(s) %s could not be "
-                     "parsed, so constructs there may be missing from the graph (callers/callees "
-                     "and search results can under-report this file). The source above is ground "
-                     "truth. (best-effort signal)",
-                     rows[i].detail && rows[i].detail[0] ? rows[i].detail : "?");
-            yyjson_mut_obj_add_strcpy(doc, root_obj, "coverage_note", note);
+    const char *end = source;
+    int lines = 0;
+    while (*end && lines < line_limit) {
+        const char *newline = strchr(end, '\n');
+        if (!newline) {
+            end += strlen(end);
             break;
         }
+        end = newline + 1;
+        lines++;
     }
-    cbm_store_free_coverage(rows, count);
+    size_t len = (size_t)(end - source);
+    char *copy = malloc(len + 1U);
+    if (!copy) {
+        return NULL;
+    }
+    memcpy(copy, source, len);
+    copy[len] = '\0';
+    return copy;
+}
+
+static void snippet_set_source_prefix(yyjson_mut_doc *doc, yyjson_mut_val *root,
+                                      const char *whole_source, int line_count, int start,
+                                      int original_end) {
+    (void)yyjson_mut_obj_remove_key(root, "source");
+    (void)yyjson_mut_obj_remove_key(root, "source_omitted");
+    (void)yyjson_mut_obj_remove_key(root, "next_start_line");
+    (void)yyjson_mut_obj_remove_key(root, "continuation_requires_higher_budget");
+    (void)yyjson_mut_obj_remove_key(root, "continuation");
+    if (line_count > 0) {
+        char *prefix = snippet_source_line_prefix(whole_source, line_count);
+        if (prefix) {
+            yyjson_mut_obj_add_strcpy(doc, root, "source", prefix);
+            free(prefix);
+        } else {
+            yyjson_mut_obj_add_bool(doc, root, "source_omitted", true);
+            line_count = 0;
+        }
+    } else {
+        yyjson_mut_obj_add_bool(doc, root, "source_omitted", true);
+    }
+    int returned_end = line_count > 0 ? start + line_count - 1 : start;
+    snippet_obj_set_int(doc, root, "end_line", returned_end);
+    snippet_obj_set_bool(doc, root, "source_truncated", true);
+    snippet_obj_set_bool(doc, root, "source_clipped", true);
+    (void)yyjson_mut_obj_remove_key(root, "truncation_reason");
+    yyjson_mut_obj_add_str(doc, root, "truncation_reason", "output_budget");
+    if (line_count > 0) {
+        yyjson_mut_obj_add_int(doc, root, "next_start_line", returned_end + 1);
+    } else {
+        yyjson_mut_obj_add_bool(doc, root, "continuation_requires_higher_budget", true);
+        yyjson_mut_obj_add_str(
+            doc, root, "continuation",
+            "raise max_output_tokens; no complete source line fits the current budget");
+    }
+    snippet_obj_set_int(doc, root, "original_end_line", original_end);
+    snippet_obj_set_int(doc, root, "source_lines_returned", line_count);
+}
+
+static char *snippet_budget_floor(bool json_format, int max_output_tokens) {
+    if (!json_format) {
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        cbm_tree_scalar_str(&sb, "source_mode", "omitted");
+        cbm_tree_scalar_bool(&sb, "truncated", true);
+        cbm_tree_scalar_str(&sb, "truncation_reason", "output_budget");
+        cbm_tree_scalar_int(&sb, "max_output_tokens", max_output_tokens);
+        cbm_tree_scalar_bool(&sb, "continuation_requires_higher_budget", true);
+        cbm_tree_scalar_str(&sb, "continuation",
+                            "raise max_output_tokens; no partial line or identifier was emitted");
+        return cbm_sb_finish(&sb);
+    }
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *root = yyjson_mut_obj(doc);
+    yyjson_mut_doc_set_root(doc, root);
+    yyjson_mut_obj_add_str(doc, root, "source_mode", "omitted");
+    yyjson_mut_obj_add_bool(doc, root, "truncated", true);
+    yyjson_mut_obj_add_str(doc, root, "truncation_reason", "output_budget");
+    yyjson_mut_obj_add_int(doc, root, "max_output_tokens", max_output_tokens);
+    yyjson_mut_obj_add_bool(doc, root, "continuation_requires_higher_budget", true);
+    yyjson_mut_obj_add_str(doc, root, "continuation",
+                           "raise max_output_tokens; no partial line or identifier was emitted");
+    char *json = yy_doc_to_str(doc);
+    yyjson_mut_doc_free(doc);
+    return json;
 }
 
 static char *build_snippet_response(cbm_mcp_server_t *srv, cbm_node_t *node,
                                     const char *match_method, bool include_neighbors,
-                                    cbm_node_t *alternatives, int alt_count) {
+                                    cbm_node_t *alternatives, int alt_count, const char *args) {
     char *root_path = get_project_root(srv, node->project);
 
-    int start = node->start_line > 0 ? node->start_line : SKIP_ONE;
-    int end = node->end_line > start ? node->end_line : start + SNIPPET_DEFAULT_LINES;
+    int original_start = node->start_line > 0 ? node->start_line : SKIP_ONE;
+    /* A one-line symbol legitimately has end == start. Treat only missing or
+     * inverted end metadata as unknown; expanding a valid one-line node by 50
+     * lines both wastes output and lies about the continuation range. */
+    int original_end =
+        node->end_line >= original_start ? node->end_line : original_start + SNIPPET_DEFAULT_LINES;
+    char *source_mode = cbm_mcp_get_string_arg(args, "source_mode");
+    bool explicit_full = source_mode && strcmp(source_mode, "full") == 0;
+    bool explicit_outline = source_mode && strcmp(source_mode, "outline") == 0;
+    bool container =
+        node->label && (strcmp(node->label, "File") == 0 || strcmp(node->label, "Module") == 0 ||
+                        strcmp(node->label, "Class") == 0 || strcmp(node->label, "Interface") == 0);
+    bool outline =
+        explicit_outline || (!explicit_full && container && original_end - original_start >= 200);
+    free(source_mode);
+
+    int start = outline ? original_start : cbm_mcp_get_int_arg(args, "start_line", original_start);
+    if (start < original_start || start > original_end) {
+        start = original_start;
+    }
+    int end = original_end;
+    int max_lines = cbm_mcp_get_int_arg(args, "max_lines", 0);
+    int max_output_tokens =
+        cbm_mcp_get_int_arg(args, "max_output_tokens", explicit_full ? 0 : 2500);
+    if (max_output_tokens < 0) {
+        max_output_tokens = 0;
+    } else if (max_output_tokens > 0 && max_output_tokens < 128) {
+        max_output_tokens = 128;
+    } else if (max_output_tokens > 1000000) {
+        max_output_tokens = 1000000;
+    }
+    if (max_lines > MCP_SNIPPET_MAX_LINES) {
+        max_lines = MCP_SNIPPET_MAX_LINES;
+    }
+    if (!outline && max_lines > 0 && start + max_lines - 1 < end) {
+        end = start + max_lines - 1;
+    }
     /* Context-bomb guard: a structural node (Module/File) spans its whole file,
      * so an unclipped read returned the ENTIRE source — a field-eval agent that
      * fell back to a Module snippet pulled 400KB in one call. Cap the line span
      * (far above any real function) and flag it; the exact range is still in
      * start_line/end_line for a targeted re-read. */
     bool snippet_clipped = false;
-    if (end - start + 1 > MCP_SNIPPET_MAX_LINES) {
+    if (!outline && end - start + 1 > MCP_SNIPPET_MAX_LINES) {
         end = start + MCP_SNIPPET_MAX_LINES - 1;
         snippet_clipped = true;
     }
+    if (!outline && end < original_end) {
+        snippet_clipped = true;
+    }
     char *abs_path = NULL;
-    char *source = resolve_snippet_source(root_path, node->file_path, start, end, &abs_path);
+    char *source =
+        outline ? NULL : resolve_snippet_source(root_path, node->file_path, start, end, &abs_path);
 
     yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
     yyjson_mut_val *root_obj = yyjson_mut_obj(doc);
@@ -8506,11 +10848,79 @@ static char *build_snippet_response(cbm_mcp_server_t *srv, cbm_node_t *node,
     yyjson_mut_obj_add_int(doc, root_obj, "start_line", start);
     yyjson_mut_obj_add_int(doc, root_obj, "end_line", end);
     if (snippet_clipped) {
-        yyjson_mut_obj_add_bool(doc, root_obj, "source_clipped", true);
-        yyjson_mut_obj_add_int(doc, root_obj, "clipped_at_lines", MCP_SNIPPET_MAX_LINES);
-    }
-
-    if (source) {
+        yyjson_mut_obj_add_bool(doc, root_obj, "source_truncated", true);
+        yyjson_mut_obj_add_bool(doc, root_obj, "source_clipped", true); /* compatibility */
+        yyjson_mut_obj_add_int(doc, root_obj, "next_start_line", end + 1);
+        yyjson_mut_obj_add_int(doc, root_obj, "original_end_line", original_end);
+    }
+
+    yyjson_mut_val *outline_members = NULL;
+    int outline_member_offset = 0;
+    int outline_members_total = 0;
+    int outline_members_returned = 0;
+    if (outline) {
+        cbm_node_t *members = NULL;
+        int member_count = 0;
+        (void)cbm_store_find_nodes_by_file(srv->store, node->project, node->file_path, &members,
+                                           &member_count);
+        if (member_count > 1) {
+            qsort(members, (size_t)member_count, sizeof(*members), snippet_member_cmp);
+        }
+        int member_limit = cbm_mcp_get_int_arg(args, "member_limit", 50);
+        int member_offset = cbm_mcp_get_int_arg(args, "member_offset", 0);
+        if (member_limit < 1) {
+            member_limit = 1;
+        } else if (member_limit > 500) {
+            member_limit = 500;
+        }
+        if (member_offset < 0) {
+            member_offset = 0;
+        }
+        int eligible = 0;
+        for (int i = 0; i < member_count; i++) {
+            if (members[i].id != node->id && members[i].start_line >= original_start &&
+                members[i].end_line <= original_end) {
+                eligible++;
+            }
+        }
+        yyjson_mut_val *member_rows = yyjson_mut_arr(doc);
+        int seen = 0;
+        int emitted = 0;
+        for (int i = 0; i < member_count && emitted < member_limit; i++) {
+            if (members[i].id == node->id || members[i].start_line < original_start ||
+                members[i].end_line > original_end) {
+                continue;
+            }
+            if (seen++ < member_offset) {
+                continue;
+            }
+            yyjson_mut_val *member = yyjson_mut_obj(doc);
+            yyjson_mut_obj_add_strcpy(doc, member, "qualified_name",
+                                      members[i].qualified_name ? members[i].qualified_name : "");
+            yyjson_mut_obj_add_strcpy(doc, member, "label",
+                                      members[i].label ? members[i].label : "");
+            yyjson_mut_obj_add_int(doc, member, "start_line", members[i].start_line);
+            yyjson_mut_obj_add_int(doc, member, "end_line", members[i].end_line);
+            yyjson_mut_arr_add_val(member_rows, member);
+            emitted++;
+        }
+        yyjson_mut_obj_add_str(doc, root_obj, "source_mode", "outline");
+        yyjson_mut_obj_add_val(doc, root_obj, "members", member_rows);
+        yyjson_mut_obj_add_int(doc, root_obj, "members_total", eligible);
+        yyjson_mut_obj_add_int(doc, root_obj, "members_returned", emitted);
+        yyjson_mut_obj_add_bool(doc, root_obj, "members_has_more",
+                                member_offset + emitted < eligible);
+        if (member_offset + emitted < eligible) {
+            yyjson_mut_obj_add_int(doc, root_obj, "next_member_offset", member_offset + emitted);
+        }
+        yyjson_mut_obj_add_bool(doc, root_obj, "full_source_available", true);
+        outline_members = member_rows;
+        outline_member_offset = member_offset;
+        outline_members_total = eligible;
+        outline_members_returned = emitted;
+        cbm_store_free_nodes(members, member_count);
+    } else if (source) {
+        yyjson_mut_obj_add_str(doc, root_obj, "source_mode", "full");
         char *safe_source = sanitize_utf8_lossy(source);
         if (safe_source) {
             yyjson_mut_obj_add_strcpy(doc, root_obj, "source", safe_source);
@@ -8519,6 +10929,7 @@ static char *build_snippet_response(cbm_mcp_server_t *srv, cbm_node_t *node,
             yyjson_mut_obj_add_str(doc, root_obj, "source", "(source not available)");
         }
     } else {
+        yyjson_mut_obj_add_str(doc, root_obj, "source_mode", "full");
         yyjson_mut_obj_add_str(doc, root_obj, "source", "(source not available)");
     }
 
@@ -8569,7 +10980,82 @@ static char *build_snippet_response(cbm_mcp_server_t *srv, cbm_node_t *node,
         yyjson_mut_obj_add_val(doc, root_obj, "alternatives", arr);
     }
 
-    char *json = yy_doc_to_str(doc);
+    bool bounded_default = max_output_tokens > 0;
+    size_t snippet_byte_budget =
+        bounded_default ? (size_t)max_output_tokens * (size_t)MCP_OUTPUT_BYTES_PER_TOKEN_ESTIMATE
+                        : (size_t)-1;
+    bool json_format = mcp_wants_json(args);
+    char *payload = snippet_render_payload(doc, args);
+
+    /* An outline is already the quality-preserving alternative to dumping a
+     * large container. If its member page is still too large, page whole
+     * member rows before considering the minimal floor; retain symbol identity
+     * and an exact continuation offset throughout. */
+    if (bounded_default && payload && strlen(payload) > snippet_byte_budget && outline &&
+        outline_members) {
+        (void)yyjson_mut_obj_remove_key(root_obj, "truncation_reason");
+        yyjson_mut_obj_add_str(doc, root_obj, "truncation_reason", "output_budget");
+        while (strlen(payload) > snippet_byte_budget && outline_members_returned > 0) {
+            free(payload);
+            outline_members_returned--;
+            yyjson_mut_arr_remove(outline_members, (size_t)outline_members_returned);
+            snippet_obj_set_int(doc, root_obj, "members_returned", outline_members_returned);
+            snippet_obj_set_bool(doc, root_obj, "members_has_more",
+                                 outline_member_offset + outline_members_returned <
+                                     outline_members_total);
+            (void)yyjson_mut_obj_remove_key(root_obj, "next_member_offset");
+            if (outline_member_offset + outline_members_returned < outline_members_total) {
+                yyjson_mut_obj_add_int(doc, root_obj, "next_member_offset",
+                                       outline_member_offset + outline_members_returned);
+            }
+            payload = snippet_render_payload(doc, args);
+            if (!payload) {
+                break;
+            }
+        }
+    }
+
+    if (bounded_default && payload && strlen(payload) > snippet_byte_budget && !outline && source) {
+        char *safe_whole_source = sanitize_utf8_lossy(source);
+        int available_lines = snippet_source_line_count(safe_whole_source);
+        int low = 0;
+        int high = available_lines;
+        int best_lines = -1;
+        char *best_payload = NULL;
+        while (low <= high) {
+            int middle = low + (high - low) / 2;
+            snippet_set_source_prefix(doc, root_obj, safe_whole_source, middle, start,
+                                      original_end);
+            char *candidate = snippet_render_payload(doc, args);
+            if (candidate && strlen(candidate) <= snippet_byte_budget) {
+                free(best_payload);
+                best_payload = candidate;
+                best_lines = middle;
+                low = middle + 1;
+            } else {
+                free(candidate);
+                high = middle - 1;
+            }
+        }
+        free(payload);
+        if (best_payload) {
+            snippet_set_source_prefix(doc, root_obj, safe_whole_source, best_lines, start,
+                                      original_end);
+            payload = best_payload;
+        } else {
+            snippet_set_source_prefix(doc, root_obj, safe_whole_source, 0, start, original_end);
+            payload = snippet_render_payload(doc, args);
+        }
+        free(safe_whole_source);
+    }
+
+    /* Large outlines/neighbor/alternative metadata still obey the default
+     * ceiling. Do not slice identifiers: if the metadata floor itself cannot
+     * fit, return a small continuation record. */
+    if (bounded_default && (!payload || strlen(payload) > snippet_byte_budget)) {
+        free(payload);
+        payload = snippet_budget_floor(json_format, max_output_tokens);
+    }
     yyjson_mut_doc_free(doc);
     yyjson_doc_free(props_doc); /* safe if NULL */
     for (int i = 0; i < nb_caller_count; i++) {
@@ -8584,8 +11070,8 @@ static char *build_snippet_response(cbm_mcp_server_t *srv, cbm_node_t *node,
     free(abs_path);
     free(source);
 
-    char *result = cbm_mcp_text_result(json, false);
-    free(json);
+    char *result = cbm_mcp_text_result(payload ? payload : "out of memory", payload == NULL);
+    free(payload);
     return result;
 }
 
@@ -8623,7 +11109,7 @@ static char *handle_get_code_snippet(cbm_mcp_server_t *srv, const char *args) {
     cbm_node_t node = {0};
     int rc = cbm_store_find_node_by_qn(store, effective_project, qn, &node);
     if (rc == CBM_STORE_OK) {
-        char *result = build_snippet_response(srv, &node, NULL, include_neighbors, NULL, 0);
+        char *result = build_snippet_response(srv, &node, NULL, include_neighbors, NULL, 0, args);
         free_node_contents(&node);
         free(qn);
         free(project);
@@ -8639,7 +11125,8 @@ static char *handle_get_code_snippet(cbm_mcp_server_t *srv, const char *args) {
     if (suffix_count == SKIP_ONE) {
         copy_node(&suffix_nodes[0], &node);
         cbm_store_free_nodes(suffix_nodes, suffix_count);
-        char *result = build_snippet_response(srv, &node, "suffix", include_neighbors, NULL, 0);
+        char *result =
+            build_snippet_response(srv, &node, "suffix", include_neighbors, NULL, 0, args);
         free_node_contents(&node);
         free(qn);
         free(project);
@@ -8656,7 +11143,8 @@ static char *handle_get_code_snippet(cbm_mcp_server_t *srv, const char *args) {
         if (!snip_ambiguous) {
             copy_node(&suffix_nodes[ssel], &node);
             cbm_store_free_nodes(suffix_nodes, suffix_count);
-            char *result = build_snippet_response(srv, &node, "suffix", include_neighbors, NULL, 0);
+            char *result =
+                build_snippet_response(srv, &node, "suffix", include_neighbors, NULL, 0, args);
             free_node_contents(&node);
             free(qn);
             free(project);
@@ -8682,39 +11170,78 @@ static char *handle_get_code_snippet(cbm_mcp_server_t *srv, const char *args) {
 
 /* ── search_code v2: graph-augmented code search ─────────────── */
 
-/* Strip non-ASCII bytes to guarantee valid UTF-8 JSON output */
-enum { ASCII_MAX = 127 };
-static void sanitize_ascii(char *s) {
-    for (unsigned char *p = (unsigned char *)s; *p; p++) {
-        if (*p > ASCII_MAX) {
-            *p = '?';
-        }
-    }
-}
-
 /* Intermediate grep match */
 typedef struct {
-    char file[CBM_SZ_512];
+    char *file;
     int line;
     char content[CBM_SZ_1K];
+    size_t content_start_byte;
+    size_t content_returned_bytes;
+    size_t content_total_bytes;
+    size_t match_start_byte;
+    size_t match_end_byte;
+    bool match_known;
+    bool content_truncated;
 } grep_match_t;
 
 /* Deduped result: one per containing graph node */
 typedef struct {
     int64_t node_id; /* 0 = raw match (no containing node) */
     char node_name[CBM_SZ_256];
-    char qualified_name[CBM_SZ_512];
+    char *qualified_name;
     char label[CBM_SZ_64];
-    char file[CBM_SZ_512];
+    char *file;
     int start_line;
     int end_line;
     int in_degree;
     int out_degree;
     int score;
-    int match_lines[CBM_SZ_64];
-    int match_count;
+    int *match_lines;
+    int match_count;        /* exact total across the complete grep stream */
+    int match_stored_count; /* bounded evidence retained for rendering */
+    int match_capacity;
 } search_result_t;
 
+typedef struct {
+    char *name;
+    int count;
+} search_dir_count_t;
+
+static bool set_search_result_identity(search_result_t *result, const cbm_node_t *node);
+static bool append_search_match_line(search_result_t *result, int line);
+
+static void free_grep_matches(grep_match_t *matches, int count) {
+    if (!matches) {
+        return;
+    }
+    for (int i = 0; i < count; i++) {
+        free(matches[i].file);
+    }
+    free(matches);
+}
+
+static void free_search_results(search_result_t *results, int count) {
+    if (!results) {
+        return;
+    }
+    for (int i = 0; i < count; i++) {
+        free(results[i].qualified_name);
+        free(results[i].file);
+        free(results[i].match_lines);
+    }
+    free(results);
+}
+
+static void free_search_dirs(search_dir_count_t *directories, int count) {
+    if (!directories) {
+        return;
+    }
+    for (int i = 0; i < count; i++) {
+        free(directories[i].name);
+    }
+    free(directories);
+}
+
 /* Score a result for ranking: project source first, vendored last, tests lowest */
 enum { SCORE_FUNC = 10, SCORE_ROUTE = 15, SCORE_VENDORED = -50, SCORE_TEST = -5 };
 enum { MAX_LINE_SPAN = 999999 };
@@ -8741,7 +11268,26 @@ static int compute_search_score(const search_result_t *r) {
 static int search_result_cmp(const void *a, const void *b) {
     const search_result_t *ra = (const search_result_t *)a;
     const search_result_t *rb = (const search_result_t *)b;
-    return rb->score - ra->score; /* descending */
+    int score_order = rb->score - ra->score; /* descending */
+    if (score_order != 0) {
+        return score_order;
+    }
+    int qn_order = strcmp(ra->qualified_name ? ra->qualified_name : "",
+                          rb->qualified_name ? rb->qualified_name : "");
+    if (qn_order != 0) {
+        return qn_order;
+    }
+    int file_order = strcmp(ra->file ? ra->file : "", rb->file ? rb->file : "");
+    if (file_order != 0) {
+        return file_order;
+    }
+    if (ra->start_line != rb->start_line) {
+        return ra->start_line < rb->start_line ? -1 : 1;
+    }
+    if (ra->end_line != rb->end_line) {
+        return ra->end_line < rb->end_line ? -1 : 1;
+    }
+    return 0;
 }
 
 /* Build the grep/search command string based on scoped vs recursive mode.
@@ -8756,20 +11302,22 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
         if (file_pattern) {
             snprintf(
                 cmd, cmd_sz,
-                "powershell -Command \"$pat = Get-Content -Encoding UTF8 -LiteralPath '%s'; "
+                "powershell -NoProfile -NonInteractive -Command \"$ErrorActionPreference = "
+                "'Stop'; $pat = Get-Content -Encoding UTF8 -LiteralPath '%s'; "
                 "Get-Content -Encoding UTF8 -LiteralPath '%s' | ForEach-Object { Select-String "
                 "-LiteralPath $_ -Pattern $pat%s "
-                "-ErrorAction SilentlyContinue }"
+                "-ErrorAction Stop }"
                 " | Where-Object { $_.Path -like '*%s' }"
                 " | ForEach-Object { $_.Path + [char]9 + $_.LineNumber + [char]9 + $_.Line }\"",
                 tmpfile, filelist, sm, file_pattern);
         } else {
             snprintf(
                 cmd, cmd_sz,
-                "powershell -Command \"$pat = Get-Content -Encoding UTF8 -LiteralPath '%s'; "
+                "powershell -NoProfile -NonInteractive -Command \"$ErrorActionPreference = "
+                "'Stop'; $pat = Get-Content -Encoding UTF8 -LiteralPath '%s'; "
                 "Get-Content -Encoding UTF8 -LiteralPath '%s' | ForEach-Object { Select-String "
                 "-LiteralPath $_ -Pattern $pat%s "
-                "-ErrorAction SilentlyContinue }"
+                "-ErrorAction Stop }"
                 " | ForEach-Object { $_.Path + [char]9 + $_.LineNumber + [char]9 + $_.Line }\"",
                 tmpfile, filelist, sm);
         }
@@ -8777,19 +11325,22 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
         if (file_pattern) {
             snprintf(
                 cmd, cmd_sz,
-                "powershell -Command \"Get-ChildItem -Recurse -Path '%s\\*' -Include '%s' -File "
-                "-ErrorAction SilentlyContinue"
+                "powershell -NoProfile -NonInteractive -Command \"$ErrorActionPreference = "
+                "'Stop'; Get-ChildItem -Recurse -Path '%s\\*' -Include '%s' -File "
+                "-ErrorAction Stop"
+                " | Sort-Object -Property FullName"
                 " | Select-String -Pattern (Get-Content -Encoding UTF8 -LiteralPath '%s')%s "
-                "-ErrorAction SilentlyContinue"
+                "-ErrorAction Stop"
                 " | ForEach-Object { $_.Path + [char]9 + $_.LineNumber + [char]9 + $_.Line }\"",
                 root_path, file_pattern, tmpfile, sm);
         } else {
             snprintf(
                 cmd, cmd_sz,
-                "powershell -Command \"Get-ChildItem -Recurse -Path '%s\\*' -File -ErrorAction "
-                "SilentlyContinue"
+                "powershell -NoProfile -NonInteractive -Command \"$ErrorActionPreference = "
+                "'Stop'; Get-ChildItem -Recurse -Path '%s\\*' -File -ErrorAction Stop"
+                " | Sort-Object -Property FullName"
                 " | Select-String -Pattern (Get-Content -Encoding UTF8 -LiteralPath '%s')%s "
-                "-ErrorAction SilentlyContinue"
+                "-ErrorAction Stop"
                 " | ForEach-Object { $_.Path + [char]9 + $_.LineNumber + [char]9 + $_.Line }\"",
                 root_path, tmpfile, sm);
         }
@@ -8797,77 +11348,131 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
 #else
     const char *flag = use_regex ? "-E" : "-F";
     if (scoped) {
-        if (file_pattern) {
-            /* -0: read NUL-separated paths from the filelist so paths containing
-             * spaces stay one argument (issue #687). Pairs with the NUL separator
-             * written by write_scoped_filelist. */
-            snprintf(cmd, cmd_sz, "xargs -0 grep -Hn %s --include='%s' -f '%s' < '%s' 2>/dev/null",
-                     flag, file_pattern, tmpfile, filelist);
-        } else {
-            snprintf(cmd, cmd_sz, "xargs -0 grep -Hn %s -f '%s' < '%s' 2>/dev/null", flag, tmpfile,
-                     filelist);
-        }
+        /* file_pattern was already applied to the canonical file list in C.
+         * Keep this scan compatible with BusyBox grep, which has no GNU
+         * --include option (the shipped Alpine/static runtime). */
+        snprintf(cmd, cmd_sz,
+                 "xargs -0 sh -c 'pat=$1; shift; if [ \"$#\" -eq 0 ]; then exit 0; fi; "
+                 "grep -Hn %s -f \"$pat\" -- \"$@\"; rc=$?; if [ \"$rc\" -eq 1 ]; then "
+                 "exit 0; fi; if [ \"$rc\" -ne 0 ]; then exit 255; fi; exit 0' sh '%s' "
+                 "< '%s' 2>/dev/null",
+                 flag, tmpfile, filelist);
     } else {
+        /* Do not pipe discovery directly into sort/xargs: POSIX sh reports only
+         * the final pipeline command, which can hide a partial find or failed
+         * sort behind a successful grep. Materialize the NUL list in the
+         * request-private scratch file and check each producer before scanning.
+         * The xargs wrapper's zero-argument guard also makes empty discovery
+         * succeed on both GNU (runs once) and BSD (runs zero times) xargs. */
         if (file_pattern) {
-            snprintf(cmd, cmd_sz, "grep -rn %s --include='%s' -f '%s' '%s' 2>/dev/null", flag,
-                     file_pattern, tmpfile, root_path);
+            snprintf(cmd, cmd_sz,
+                     "fl='%s'; find '%s' -type f -name '%s' -print0 > \"$fl\" 2>/dev/null; "
+                     "rc=$?; if [ \"$rc\" -ne 0 ]; then exit \"$rc\"; fi; "
+                     "LC_ALL=C sort -z -o \"$fl\" \"$fl\" 2>/dev/null; rc=$?; "
+                     "if [ \"$rc\" -ne 0 ]; then exit \"$rc\"; fi; "
+                     "xargs -0 sh -c 'pat=$1; shift; if [ \"$#\" -eq 0 ]; then exit 0; fi; "
+                     "grep -Hn %s -f \"$pat\" -- \"$@\"; rc=$?; if [ \"$rc\" -eq 1 ]; then "
+                     "exit 0; fi; if [ \"$rc\" -ne 0 ]; then exit 255; fi; exit 0' sh '%s' "
+                     "< \"$fl\" 2>/dev/null",
+                     filelist, root_path, file_pattern, flag, tmpfile);
         } else {
-            snprintf(cmd, cmd_sz, "grep -rn %s -f '%s' '%s' 2>/dev/null", flag, tmpfile, root_path);
+            snprintf(cmd, cmd_sz,
+                     "fl='%s'; find '%s' -type f -print0 > \"$fl\" 2>/dev/null; rc=$?; "
+                     "if [ \"$rc\" -ne 0 ]; then exit \"$rc\"; fi; "
+                     "LC_ALL=C sort -z -o \"$fl\" \"$fl\" 2>/dev/null; rc=$?; "
+                     "if [ \"$rc\" -ne 0 ]; then exit \"$rc\"; fi; "
+                     "xargs -0 sh -c 'pat=$1; shift; if [ \"$#\" -eq 0 ]; then exit 0; fi; "
+                     "grep -Hn %s -f \"$pat\" -- \"$@\"; rc=$?; if [ \"$rc\" -eq 1 ]; then "
+                     "exit 0; fi; if [ \"$rc\" -ne 0 ]; then exit 255; fi; exit 0' sh '%s' "
+                     "< \"$fl\" 2>/dev/null",
+                     filelist, root_path, flag, tmpfile);
         }
     }
 #endif
 }
 
+static bool search_subprocess_succeeded(int status) {
+#ifdef _WIN32
+    return status == 0;
+#else
+    return status >= 0 && WIFEXITED(status) && WEXITSTATUS(status) == 0;
+#endif
+}
+
 /* Build deduplicated file list from search results + raw matches. */
 static yyjson_mut_val *build_dedup_files_array(yyjson_mut_doc *doc, search_result_t *sr,
-                                               int output_count, grep_match_t *raw, int raw_count) {
+                                               int result_start, int output_count,
+                                               grep_match_t *raw, int raw_start, int raw_count) {
+    (void)raw_start;
     yyjson_mut_val *files_arr = yyjson_mut_arr(doc);
-    char *seen_files[CBM_SZ_512];
+    size_t seen_capacity = (size_t)output_count + (size_t)raw_count;
+    const char **seen_files = seen_capacity > 0 ? calloc(seen_capacity, sizeof(*seen_files)) : NULL;
+    if (!files_arr || (seen_capacity > 0 && !seen_files)) {
+        free(seen_files);
+        return NULL;
+    }
     int seen_count = 0;
     for (int fi = 0; fi < output_count; fi++) {
+        int result_index = result_start + fi;
         bool dup = false;
         for (int j = 0; j < seen_count; j++) {
-            if (strcmp(seen_files[j], sr[fi].file) == 0) {
+            if (strcmp(seen_files[j], sr[result_index].file) == 0) {
                 dup = true;
                 break;
             }
         }
-        if (!dup && seen_count < CBM_SZ_512) {
-            seen_files[seen_count++] = sr[fi].file;
-            yyjson_mut_arr_add_str(doc, files_arr, sr[fi].file);
+        if (!dup) {
+            seen_files[seen_count++] = sr[result_index].file;
+            yyjson_mut_arr_add_str(doc, files_arr, sr[result_index].file);
         }
     }
-    for (int fi = 0; fi < raw_count && seen_count < CBM_SZ_512; fi++) {
+    for (int fi = 0; fi < raw_count; fi++) {
+        /* `raw` contains only the requested page. raw_start is the global
+         * offset used for continuation metadata, not an array index. */
+        int raw_index = fi;
         bool dup = false;
         for (int j = 0; j < seen_count; j++) {
-            if (strcmp(seen_files[j], raw[fi].file) == 0) {
+            if (strcmp(seen_files[j], raw[raw_index].file) == 0) {
                 dup = true;
                 break;
             }
         }
         if (!dup) {
-            seen_files[seen_count++] = raw[fi].file;
-            yyjson_mut_arr_add_str(doc, files_arr, raw[fi].file);
+            seen_files[seen_count++] = raw[raw_index].file;
+            yyjson_mut_arr_add_str(doc, files_arr, raw[raw_index].file);
         }
     }
+    free(seen_files);
     return files_arr;
 }
 
 /* Attach source or context lines to a search result JSON item. */
 static void attach_result_source(yyjson_mut_doc *doc, yyjson_mut_val *item, search_result_t *r,
-                                 int mode, int context_lines, const char *root_path) {
+                                 int mode, int context_lines, int source_max_lines,
+                                 const char *root_path) {
     enum { MODE_FULL = 1 };
     if (r->start_line <= 0 || r->end_line <= 0) {
         return;
     }
-    char abs_path[CBM_SZ_1K];
-    snprintf(abs_path, sizeof(abs_path), "%s/%s", root_path, r->file);
+    size_t root_length = strlen(root_path);
+    size_t file_length = strlen(r->file);
+    if (root_length > SIZE_MAX - file_length - 2U) {
+        return;
+    }
+    char *abs_path = malloc(root_length + file_length + 2U);
+    if (!abs_path) {
+        return;
+    }
+    memcpy(abs_path, root_path, root_length);
+    abs_path[root_length] = '/';
+    memcpy(abs_path + root_length + 1U, r->file, file_length + 1U);
 
     /* Containment: a search result whose indexed path resolves outside the
      * project root (a `..` segment, or a symlink/junction that discovery
      * followed) must not be read back into the response. Same guard the
      * snippet path already uses. */
     if (!cbm_path_within_root(root_path, abs_path)) {
+        free(abs_path);
         return;
     }
 
@@ -8876,15 +11481,20 @@ static void attach_result_source(yyjson_mut_doc *doc, yyjson_mut_val *item, sear
          * whole-symbol dumps ran to 5.7KB × N hits (142KB responses). The
          * complete symbol stays one get_code_snippet call away;
          * source_start/source_truncated make the cut explicit. */
-        enum { SC_FULL_MAX_LINES = 60, SC_FULL_LEAD = 5 };
+        enum { SC_FULL_LEAD = 5 };
+        if (source_max_lines <= 0) {
+            yyjson_mut_obj_add_bool(doc, item, "source_omitted", true);
+            free(abs_path);
+            return;
+        }
         int s = r->start_line;
         int e = r->end_line;
         bool truncated = false;
-        if (e - s + 1 > SC_FULL_MAX_LINES) {
+        if (e - s + 1 > source_max_lines) {
             if (r->match_count > 0 && r->match_lines[0] - SC_FULL_LEAD > s) {
                 s = r->match_lines[0] - SC_FULL_LEAD;
             }
-            e = s + SC_FULL_MAX_LINES - 1;
+            e = s + source_max_lines - 1;
             if (e > r->end_line) {
                 e = r->end_line;
             }
@@ -8892,7 +11502,7 @@ static void attach_result_source(yyjson_mut_doc *doc, yyjson_mut_val *item, sear
         }
         char *source = read_file_lines(abs_path, s, e);
         if (source) {
-            sanitize_ascii(source);
+            sanitize_utf8_inplace(source);
             yyjson_mut_obj_add_strcpy(doc, item, "source", source);
             free(source);
             if (truncated) {
@@ -8908,63 +11518,95 @@ static void attach_result_source(yyjson_mut_doc *doc, yyjson_mut_val *item, sear
         }
         char *ctx = read_file_lines(abs_path, ctx_start, ctx_end);
         if (ctx) {
-            sanitize_ascii(ctx);
+            sanitize_utf8_inplace(ctx);
             yyjson_mut_obj_add_strcpy(doc, item, "context", ctx);
             yyjson_mut_obj_add_int(doc, item, "context_start", ctx_start);
             free(ctx);
         }
     }
+    free(abs_path);
 }
 
-/* Build directory distribution object from search results (top-level dir → count). */
-/* Aggregate hits by top-level directory. Shared by the JSON object and the
- * TOON table emission. Returns the number of distinct directories. */
-static int aggregate_search_dirs(search_result_t *sr, int sr_count, char dir_names[][CBM_SZ_128],
-                                 int *dir_counts, int max_dirs) {
+/* Aggregate hits by top-level directory. Directory keys are allocation-backed:
+ * truncating them used to merge distinct directories that shared their first
+ * 127 bytes, making the diagnostic count look exact when it was not. */
+static bool aggregate_search_dirs(search_result_t *sr, int sr_count,
+                                  search_dir_count_t **directories_out, int *count_out) {
+    *directories_out = NULL;
+    *count_out = 0;
+    if (sr_count <= 0) {
+        return true;
+    }
+    search_dir_count_t *directories = calloc((size_t)sr_count, sizeof(*directories));
+    if (!directories) {
+        return false;
+    }
     int dir_n = 0;
     for (int di = 0; di < sr_count; di++) {
-        char top[CBM_SZ_128] = "";
-        const char *slash = strchr(sr[di].file, '/');
-        if (slash) {
-            size_t dlen = (size_t)(slash - sr[di].file + SKIP_ONE);
-            if (dlen >= sizeof(top)) {
-                dlen = sizeof(top) - SKIP_ONE;
-            }
-            memcpy(top, sr[di].file, dlen);
-            top[dlen] = '\0';
-        } else {
-            snprintf(top, sizeof(top), "%s", sr[di].file);
-        }
+        const char *file = sr[di].file ? sr[di].file : "";
+        const char *slash = strchr(file, '/');
+        size_t directory_length = slash ? (size_t)(slash - file + SKIP_ONE) : strlen(file);
         int found = CBM_NOT_FOUND;
         for (int d = 0; d < dir_n; d++) {
-            if (strcmp(dir_names[d], top) == 0) {
+            if (strlen(directories[d].name) == directory_length &&
+                memcmp(directories[d].name, file, directory_length) == 0) {
                 found = d;
                 break;
             }
         }
         if (found >= 0) {
-            dir_counts[found]++;
-        } else if (dir_n < max_dirs) {
-            snprintf(dir_names[dir_n], CBM_SZ_128, "%s", top);
-            dir_counts[dir_n] = SKIP_ONE;
+            directories[found].count++;
+        } else {
+            directories[dir_n].name = cbm_strndup(file, directory_length);
+            if (!directories[dir_n].name) {
+                free_search_dirs(directories, dir_n);
+                return false;
+            }
+            directories[dir_n].count = SKIP_ONE;
             dir_n++;
         }
     }
-    return dir_n;
+    *directories_out = directories;
+    *count_out = dir_n;
+    return true;
+}
+
+static bool raw_content_has_next(const grep_match_t *match) {
+    return match->content_start_byte + match->content_returned_bytes < match->content_total_bytes;
+}
+
+static bool raw_match_fully_returned(const grep_match_t *match) {
+    if (!match->match_known) {
+        return false;
+    }
+    size_t content_end = match->content_start_byte + match->content_returned_bytes;
+    return match->content_start_byte <= match->match_start_byte &&
+           content_end >= match->match_end_byte;
 }
 
-static yyjson_mut_val *build_dir_distribution(yyjson_mut_doc *doc, search_result_t *sr,
-                                              int sr_count) {
-    yyjson_mut_val *dirs = yyjson_mut_obj(doc);
-    char dir_names[CBM_SZ_64][CBM_SZ_128];
-    int dir_counts[CBM_SZ_64];
-    int dir_n = aggregate_search_dirs(sr, sr_count, dir_names, dir_counts, CBM_SZ_64);
-    for (int d = 0; d < dir_n; d++) {
-        yyjson_mut_val *key = yyjson_mut_strcpy(doc, dir_names[d]);
-        yyjson_mut_val *val = yyjson_mut_int(doc, dir_counts[d]);
-        yyjson_mut_obj_add(dirs, key, val);
+static int search_match_lines_shown(const search_result_t *result, int match_limit) {
+    return result->match_stored_count < match_limit ? result->match_stored_count : match_limit;
+}
+
+static char *search_match_lines_text(const search_result_t *result, int match_limit) {
+    int shown = search_match_lines_shown(result, match_limit);
+    size_t capacity = (size_t)shown * 16U + 1U;
+    char *text = malloc(capacity);
+    if (!text) {
+        return NULL;
     }
-    return dirs;
+    size_t used = 0;
+    text[0] = '\0';
+    for (int i = 0; i < shown; i++) {
+        int written = snprintf(text + used, capacity - used, "%s%d", i > 0 ? ";" : "",
+                               result->match_lines[i]);
+        if (written < 0 || (size_t)written >= capacity - used) {
+            free(text);
+            return NULL;
+        }
+        used += (size_t)written;
+    }
+    return text;
 }
 
 /* TOON emission for compact-mode search results: one row per hit
@@ -8972,77 +11614,232 @@ static yyjson_mut_val *build_dir_distribution(yyjson_mut_doc *doc, search_result
  * qn's last segment), a raw[] table for uncorrelated matches, a dirs[]
  * distribution table, and the summary scalars. */
 static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep_match_t *raw,
-                                         int raw_count, int gm_count, int limit,
-                                         bool warn_literal_pipe, uint64_t elapsed_ms) {
-    enum { MAX_RAW = 20, SEARCH_SLOW_MS = 5000 };
+                                         int raw_count, int raw_content_truncated, int gm_count,
+                                         int result_start, int result_limit, int output_count,
+                                         int raw_start, int raw_output, int directory_start,
+                                         int directory_output, int raw_limit, int directory_limit,
+                                         int match_limit, bool scan_saturated,
+                                         bool warn_literal_pipe, uint64_t elapsed_ms,
+                                         bool budget_hit, int source_lines_returned) {
+    enum { SEARCH_SLOW_MS = 5000 };
     cbm_sb_t sb;
     cbm_sb_init(&sb);
 
-    int output_count = sr_count < limit ? sr_count : limit;
-    static const char *const cols[] = {"qn", "label", "file", "lines", "matches", "in", "out"};
-    cbm_tree_table_header(&sb, "results", output_count, cols, 7);
-    for (int ri = 0; ri < output_count; ri++) {
-        search_result_t *r = &sr[ri];
+    static const char *const cols[] = {"qn",      "label",           "file", "lines",
+                                       "matches", "matches_omitted", "in",   "out"};
+    typedef struct {
         char lines[CBM_SZ_32];
+        char *matches;
+        char matches_omitted[CBM_SZ_32];
+        char inbound[CBM_SZ_32];
+        char outbound[CBM_SZ_32];
+    } search_tree_row_t;
+    search_tree_row_t *rendered =
+        output_count > 0 ? calloc((size_t)output_count, sizeof(*rendered)) : NULL;
+    const char **cells =
+        output_count > 0 ? calloc((size_t)output_count * 8U, sizeof(*cells)) : NULL;
+    if (output_count > 0 && (!rendered || !cells)) {
+        free(cells);
+        free(rendered);
+        cbm_sb_free(&sb);
+        return NULL;
+    }
+    for (int ri = 0; ri < output_count; ri++) {
+        search_result_t *r = &sr[result_start + ri];
         if (r->start_line > 0) {
-            snprintf(lines, sizeof(lines), "%d-%d", r->start_line,
+            snprintf(rendered[ri].lines, sizeof(rendered[ri].lines), "%d-%d", r->start_line,
                      r->end_line > r->start_line ? r->end_line : r->start_line);
-        } else {
-            lines[0] = '\0';
-        }
-        /* match line numbers ';'-joined (no comma → no cell quoting) */
-        char matches[CBM_SZ_256];
-        size_t mpos = 0;
-        matches[0] = '\0';
-        for (int j = 0; j < r->match_count && mpos + 12 < sizeof(matches); j++) {
-            int n = snprintf(matches + mpos, sizeof(matches) - mpos, "%s%d", j > 0 ? ";" : "",
-                             r->match_lines[j]);
-            if (n < 0) {
-                break;
+        }
+        rendered[ri].matches = search_match_lines_text(r, match_limit);
+        if (!rendered[ri].matches) {
+            for (int j = 0; j < ri; j++) {
+                free(rendered[j].matches);
             }
-            mpos += (size_t)n;
+            free(cells);
+            free(rendered);
+            cbm_sb_free(&sb);
+            return NULL;
         }
-        cbm_tree_row_begin(&sb);
-        cbm_tree_cell_str(&sb, r->qualified_name, true);
-        cbm_tree_cell_str(&sb, r->label, false);
-        cbm_tree_cell_str(&sb, r->file, false);
-        cbm_tree_cell_str(&sb, lines, false);
-        cbm_tree_cell_str(&sb, matches, false);
-        cbm_tree_cell_int(&sb, r->in_degree, false);
-        cbm_tree_cell_int(&sb, r->out_degree, false);
-        cbm_tree_row_end(&sb);
+        snprintf(rendered[ri].matches_omitted, sizeof(rendered[ri].matches_omitted), "%d",
+                 r->match_count - search_match_lines_shown(r, match_limit));
+        snprintf(rendered[ri].inbound, sizeof(rendered[ri].inbound), "%d", r->in_degree);
+        snprintf(rendered[ri].outbound, sizeof(rendered[ri].outbound), "%d", r->out_degree);
+        size_t base = (size_t)ri * 8U;
+        cells[base] = r->qualified_name;
+        cells[base + 1] = r->label;
+        cells[base + 2] = r->file;
+        cells[base + 3] = rendered[ri].lines;
+        cells[base + 4] = rendered[ri].matches;
+        cells[base + 5] = rendered[ri].matches_omitted;
+        cells[base + 6] = rendered[ri].inbound;
+        cells[base + 7] = rendered[ri].outbound;
+    }
+    if (output_count > 0 && rendered && cells) {
+        static const bool string_cols[] = {true, true, true, true, true, false, false, false};
+        static const bool prefix_cols[] = {true, false, true, false, false, false, false, false};
+        cbm_tree_table_rows_profiled(&sb, "results", output_count, cols, 8, cells, string_cols,
+                                     prefix_cols);
+    } else {
+        cbm_tree_table_header(&sb, "results", 0, cols, 8);
+    }
+    for (int ri = 0; ri < output_count; ri++) {
+        free(rendered[ri].matches);
     }
+    free(cells);
+    free(rendered);
 
-    int raw_output = raw_count < MAX_RAW ? raw_count : MAX_RAW;
     if (raw_output > 0) {
-        static const char *const rcols[] = {"file", "line", "content"};
-        cbm_tree_table_header(&sb, "raw", raw_output, rcols, 3);
-        for (int ri = 0; ri < raw_output; ri++) {
-            cbm_tree_row_begin(&sb);
-            cbm_tree_cell_str(&sb, raw[ri].file, true);
-            cbm_tree_cell_int(&sb, raw[ri].line, false);
-            cbm_tree_cell_str(&sb, raw[ri].content, false);
-            cbm_tree_row_end(&sb);
+        static const char *const rcols[] = {"file",
+                                            "line",
+                                            "content",
+                                            "content_start_byte",
+                                            "content_returned_bytes",
+                                            "content_total_bytes",
+                                            "match_start_byte",
+                                            "match_end_byte",
+                                            "content_has_more",
+                                            "content_next_offset",
+                                            "match_fully_returned"};
+        enum { RAW_COLS = 11, RAW_TEXT_FIELDS = 9 };
+        const char **raw_cells = calloc((size_t)raw_output * RAW_COLS, sizeof(*raw_cells));
+        char (*raw_text)[RAW_TEXT_FIELDS][CBM_SZ_32] =
+            calloc((size_t)raw_output, sizeof(*raw_text));
+        if (!raw_cells || !raw_text) {
+            free(raw_text);
+            free(raw_cells);
+            cbm_sb_free(&sb);
+            return NULL;
         }
+        for (int ri = 0; ri < raw_output; ri++) {
+            int raw_index = ri;
+            grep_match_t *r = &raw[raw_index];
+            snprintf(raw_text[ri][0], sizeof(raw_text[ri][0]), "%d", r->line);
+            snprintf(raw_text[ri][1], sizeof(raw_text[ri][1]), "%zu", r->content_start_byte);
+            snprintf(raw_text[ri][2], sizeof(raw_text[ri][2]), "%zu", r->content_returned_bytes);
+            snprintf(raw_text[ri][3], sizeof(raw_text[ri][3]), "%zu", r->content_total_bytes);
+            if (r->match_known) {
+                snprintf(raw_text[ri][4], sizeof(raw_text[ri][4]), "%zu", r->match_start_byte);
+                snprintf(raw_text[ri][5], sizeof(raw_text[ri][5]), "%zu", r->match_end_byte);
+            }
+            snprintf(raw_text[ri][6], sizeof(raw_text[ri][6]), "%s",
+                     raw_content_has_next(r) ? "true" : "false");
+            if (raw_content_has_next(r)) {
+                snprintf(raw_text[ri][7], sizeof(raw_text[ri][7]), "%zu",
+                         r->content_start_byte + r->content_returned_bytes);
+            }
+            snprintf(raw_text[ri][8], sizeof(raw_text[ri][8]), "%s",
+                     raw_match_fully_returned(r) ? "true" : "false");
+            size_t base = (size_t)ri * RAW_COLS;
+            raw_cells[base] = r->file;
+            raw_cells[base + 1U] = raw_text[ri][0];
+            raw_cells[base + 2U] = r->content;
+            for (size_t field = 1; field < RAW_TEXT_FIELDS; field++) {
+                raw_cells[base + field + 2U] = raw_text[ri][field];
+            }
+        }
+        static const bool raw_string_cols[] = {true,  false, true,  false, false, false,
+                                               false, false, false, false, false};
+        static const bool raw_prefix_cols[] = {true,  false, false, false, false, false,
+                                               false, false, false, false, false};
+        cbm_tree_table_rows_profiled(&sb, "raw", raw_output, rcols, RAW_COLS, raw_cells,
+                                     raw_string_cols, raw_prefix_cols);
+        free(raw_text);
+        free(raw_cells);
+    }
+
+    search_dir_count_t *directories = NULL;
+    int dir_n = 0;
+    if (!aggregate_search_dirs(sr, sr_count, &directories, &dir_n)) {
+        cbm_sb_free(&sb);
+        return NULL;
     }
-
-    char dir_names[CBM_SZ_64][CBM_SZ_128];
-    int dir_counts[CBM_SZ_64];
-    int dir_n = aggregate_search_dirs(sr, sr_count, dir_names, dir_counts, CBM_SZ_64);
-    if (dir_n > 0) {
+    if (directory_start > dir_n) {
+        directory_start = dir_n;
+    }
+    if (directory_output > dir_n - directory_start) {
+        directory_output = dir_n - directory_start;
+    }
+    if (directory_output > 0) {
         static const char *const dcols[] = {"dir", "hits"};
-        cbm_tree_table_header(&sb, "dirs", dir_n, dcols, 2);
-        for (int d = 0; d < dir_n; d++) {
-            cbm_tree_row_begin(&sb);
-            cbm_tree_cell_str(&sb, dir_names[d], true);
-            cbm_tree_cell_int(&sb, dir_counts[d], false);
-            cbm_tree_row_end(&sb);
+        const char **dir_cells = calloc((size_t)directory_output * 2U, sizeof(*dir_cells));
+        char (*count_text)[CBM_SZ_32] = calloc((size_t)directory_output, sizeof(*count_text));
+        if (!dir_cells || !count_text) {
+            free(count_text);
+            free(dir_cells);
+            free_search_dirs(directories, dir_n);
+            cbm_sb_free(&sb);
+            return NULL;
         }
+        for (int d = 0; d < directory_output; d++) {
+            int directory_index = directory_start + d;
+            snprintf(count_text[d], sizeof(count_text[d]), "%d",
+                     directories[directory_index].count);
+            dir_cells[(size_t)d * 2U] = directories[directory_index].name;
+            dir_cells[(size_t)d * 2U + 1U] = count_text[d];
+        }
+        static const bool dir_string_cols[] = {true, false};
+        static const bool dir_prefix_cols[] = {true, false};
+        cbm_tree_table_rows_profiled(&sb, "directories", directory_output, dcols, 2, dir_cells,
+                                     dir_string_cols, dir_prefix_cols);
+        free(count_text);
+        free(dir_cells);
     }
+    free_search_dirs(directories, dir_n);
 
     cbm_tree_scalar_int(&sb, "total_grep_matches", gm_count);
     cbm_tree_scalar_int(&sb, "total_results", sr_count);
     cbm_tree_scalar_int(&sb, "raw_match_count", raw_count);
+    cbm_tree_scalar_str(&sb, "total_relation", scan_saturated ? "gte" : "eq");
+    cbm_tree_scalar_int(&sb, "result_offset", result_start);
+    cbm_tree_scalar_int(&sb, "results_returned", output_count);
+    bool has_more = result_start + output_count < sr_count;
+    cbm_tree_scalar_bool(&sb, "has_more", has_more);
+    if (has_more && output_count > 0) {
+        cbm_tree_scalar_int(&sb, "next_offset", result_start + output_count);
+    } else if (has_more) {
+        cbm_tree_scalar_bool(&sb,
+                             result_limit == 0 ? "result_continuation_requires_positive_limit"
+                                               : "result_continuation_requires_higher_budget",
+                             true);
+    }
+    cbm_tree_scalar_int(&sb, "raw_returned", raw_output);
+    bool raw_has_more = raw_start + raw_output < raw_count;
+    cbm_tree_scalar_bool(&sb, "raw_has_more", raw_has_more);
+    if (raw_has_more && raw_output > 0) {
+        cbm_tree_scalar_int(&sb, "raw_next_offset", raw_start + raw_output);
+    } else if (raw_has_more) {
+        cbm_tree_scalar_bool(&sb,
+                             raw_limit == 0 ? "raw_continuation_requires_positive_limit"
+                                            : "raw_continuation_requires_higher_budget",
+                             true);
+    }
+    if (raw_content_truncated > 0) {
+        cbm_tree_scalar_int(&sb, "raw_content_truncated", raw_content_truncated);
+    }
+    cbm_tree_scalar_int(&sb, "directories_total", dir_n);
+    cbm_tree_scalar_int(&sb, "directories_returned", directory_output);
+    bool directories_has_more = directory_start + directory_output < dir_n;
+    cbm_tree_scalar_bool(&sb, "directories_has_more", directories_has_more);
+    if (directories_has_more && directory_output > 0) {
+        cbm_tree_scalar_int(&sb, "directory_next_offset", directory_start + directory_output);
+    } else if (directories_has_more) {
+        cbm_tree_scalar_bool(&sb,
+                             directory_limit == 0 ? "directory_continuation_requires_positive_limit"
+                                                  : "directory_continuation_requires_higher_budget",
+                             true);
+    }
+    if (scan_saturated) {
+        cbm_tree_scalar_bool(&sb, "scan_saturated", true);
+    }
+    cbm_tree_scalar_bool(&sb, "truncated",
+                         has_more || raw_has_more || directories_has_more || scan_saturated ||
+                             budget_hit);
+    if (budget_hit) {
+        cbm_tree_scalar_str(&sb, "truncation_reason", "output_budget");
+    }
+    if (source_lines_returned >= 0) {
+        cbm_tree_scalar_int(&sb, "source_max_lines_returned", source_lines_returned);
+    }
     cbm_tree_scalar_int(&sb, "elapsed_ms", (long long)elapsed_ms);
     if (warn_literal_pipe) {
         cbm_tree_scalar_str(&sb, "warning",
@@ -9059,28 +11856,33 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
 }
 
 /* Phase 4: assemble JSON output from search results */
-static char *assemble_search_output(search_result_t *sr, int sr_count, grep_match_t *raw,
-                                    int raw_count, int gm_count, int limit, int mode,
-                                    int context_lines, const char *root_path,
-                                    bool warn_literal_pipe, uint64_t elapsed_ms) {
+static char *assemble_search_output(
+    search_result_t *sr, int sr_count, grep_match_t *raw, int raw_count, int raw_content_truncated,
+    int gm_count, int result_start, int result_limit, int output_count, int raw_start,
+    int raw_output, int directory_start, int directory_output, int raw_limit, int directory_limit,
+    int match_limit, int mode, int context_lines, int source_max_lines, const char *root_path,
+    bool scan_saturated, bool warn_literal_pipe, uint64_t elapsed_ms, bool budget_hit) {
     enum { MODE_COMPACT = 0, MODE_FULL = 1, MODE_FILES = 2, SEARCH_SLOW_MS = 5000 };
 
     yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
     yyjson_mut_val *root_obj = yyjson_mut_obj(doc);
     yyjson_mut_doc_set_root(doc, root_obj);
 
-    int output_count = sr_count < limit ? sr_count : limit;
-
     if (mode == MODE_FILES) {
-        yyjson_mut_obj_add_val(doc, root_obj, "files",
-                               build_dedup_files_array(doc, sr, output_count, raw, raw_count));
+        yyjson_mut_val *files = build_dedup_files_array(doc, sr, result_start, output_count, raw,
+                                                        raw_start, raw_output);
+        if (!files) {
+            yyjson_mut_doc_free(doc);
+            return NULL;
+        }
+        yyjson_mut_obj_add_val(doc, root_obj, "files", files);
     } else {
         /* json-stringified tree: cols + column-ordered row arrays. FULL mode
          * appends a per-row object cell with the (guarded, windowed) source —
          * attach_result_source semantics unchanged. */
         yyjson_mut_val *jcols = yyjson_mut_arr(doc);
-        static const char *const sc_cols[] = {"qn",      "label", "file", "lines",
-                                              "matches", "in",    "out"};
+        static const char *const sc_cols[] = {"qn",      "label",           "file", "lines",
+                                              "matches", "matches_omitted", "in",   "out"};
         for (size_t ci = 0; ci < sizeof(sc_cols) / sizeof(sc_cols[0]); ci++) {
             yyjson_mut_arr_add_str(doc, jcols, sc_cols[ci]);
         }
@@ -9091,7 +11893,7 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
 
         yyjson_mut_val *results_arr = yyjson_mut_arr(doc);
         for (int ri = 0; ri < output_count; ri++) {
-            search_result_t *r = &sr[ri];
+            search_result_t *r = &sr[result_start + ri];
             char lines[CBM_SZ_32];
             if (r->start_line > 0) {
                 snprintf(lines, sizeof(lines), "%d-%d", r->start_line,
@@ -9105,47 +11907,148 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
             yyjson_mut_arr_add_strcpy(doc, row, r->file);
             yyjson_mut_arr_add_strcpy(doc, row, lines);
             yyjson_mut_val *ml = yyjson_mut_arr(doc);
-            for (int j = 0; j < r->match_count; j++) {
+            int matches_shown = search_match_lines_shown(r, match_limit);
+            for (int j = 0; j < matches_shown; j++) {
                 yyjson_mut_arr_add_int(doc, ml, r->match_lines[j]);
             }
             yyjson_mut_arr_add_val(row, ml);
+            yyjson_mut_arr_add_int(doc, row, r->match_count - matches_shown);
             yyjson_mut_arr_add_int(doc, row, r->in_degree);
             yyjson_mut_arr_add_int(doc, row, r->out_degree);
             if (mode == MODE_FULL) {
                 yyjson_mut_val *src = yyjson_mut_obj(doc);
-                attach_result_source(doc, src, r, mode, context_lines, root_path);
+                attach_result_source(doc, src, r, mode, context_lines, source_max_lines, root_path);
                 yyjson_mut_arr_add_val(row, src);
             }
             yyjson_mut_arr_add_val(results_arr, row);
         }
         yyjson_mut_obj_add_val(doc, root_obj, "rows", results_arr);
 
-        enum { MAX_RAW = 20 };
         yyjson_mut_val *raw_obj = yyjson_mut_obj(doc);
         yyjson_mut_val *rcols = yyjson_mut_arr(doc);
         yyjson_mut_arr_add_str(doc, rcols, "file");
         yyjson_mut_arr_add_str(doc, rcols, "line");
         yyjson_mut_arr_add_str(doc, rcols, "content");
+        yyjson_mut_arr_add_str(doc, rcols, "content_start_byte");
+        yyjson_mut_arr_add_str(doc, rcols, "content_returned_bytes");
+        yyjson_mut_arr_add_str(doc, rcols, "content_total_bytes");
+        yyjson_mut_arr_add_str(doc, rcols, "match_start_byte");
+        yyjson_mut_arr_add_str(doc, rcols, "match_end_byte");
+        yyjson_mut_arr_add_str(doc, rcols, "content_has_more");
+        yyjson_mut_arr_add_str(doc, rcols, "content_next_offset");
+        yyjson_mut_arr_add_str(doc, rcols, "match_fully_returned");
         yyjson_mut_obj_add_val(doc, raw_obj, "cols", rcols);
         yyjson_mut_val *raw_arr = yyjson_mut_arr(doc);
-        int raw_output = raw_count < MAX_RAW ? raw_count : MAX_RAW;
         for (int ri = 0; ri < raw_output; ri++) {
+            int raw_index = ri;
             yyjson_mut_val *row = yyjson_mut_arr(doc);
-            yyjson_mut_arr_add_str(doc, row, raw[ri].file);
-            yyjson_mut_arr_add_int(doc, row, raw[ri].line);
-            yyjson_mut_arr_add_str(doc, row, raw[ri].content);
+            yyjson_mut_arr_add_str(doc, row, raw[raw_index].file);
+            yyjson_mut_arr_add_int(doc, row, raw[raw_index].line);
+            yyjson_mut_arr_add_str(doc, row, raw[raw_index].content);
+            yyjson_mut_arr_add_uint(doc, row, raw[raw_index].content_start_byte);
+            yyjson_mut_arr_add_uint(doc, row, raw[raw_index].content_returned_bytes);
+            yyjson_mut_arr_add_uint(doc, row, raw[raw_index].content_total_bytes);
+            if (raw[raw_index].match_known) {
+                yyjson_mut_arr_add_uint(doc, row, raw[raw_index].match_start_byte);
+                yyjson_mut_arr_add_uint(doc, row, raw[raw_index].match_end_byte);
+            } else {
+                yyjson_mut_arr_add_null(doc, row);
+                yyjson_mut_arr_add_null(doc, row);
+            }
+            yyjson_mut_arr_add_bool(doc, row, raw_content_has_next(&raw[raw_index]));
+            if (raw_content_has_next(&raw[raw_index])) {
+                yyjson_mut_arr_add_uint(doc, row,
+                                        raw[raw_index].content_start_byte +
+                                            raw[raw_index].content_returned_bytes);
+            } else {
+                yyjson_mut_arr_add_null(doc, row);
+            }
+            yyjson_mut_arr_add_bool(doc, row, raw_match_fully_returned(&raw[raw_index]));
             yyjson_mut_arr_add_val(raw_arr, row);
         }
         yyjson_mut_obj_add_val(doc, raw_obj, "rows", raw_arr);
         yyjson_mut_obj_add_val(doc, root_obj, "raw_matches", raw_obj);
     }
 
-    yyjson_mut_obj_add_val(doc, root_obj, "directories", build_dir_distribution(doc, sr, sr_count));
+    search_dir_count_t *directories = NULL;
+    int dir_total = 0;
+    if (!aggregate_search_dirs(sr, sr_count, &directories, &dir_total)) {
+        yyjson_mut_doc_free(doc);
+        return NULL;
+    }
+    if (directory_start > dir_total) {
+        directory_start = dir_total;
+    }
+    if (directory_output > dir_total - directory_start) {
+        directory_output = dir_total - directory_start;
+    }
+    yyjson_mut_val *directory_object = yyjson_mut_obj(doc);
+    for (int d = 0; d < directory_output; d++) {
+        int directory_index = directory_start + d;
+        yyjson_mut_val *key = yyjson_mut_strcpy(doc, directories[directory_index].name);
+        yyjson_mut_val *value = yyjson_mut_int(doc, directories[directory_index].count);
+        yyjson_mut_obj_add(directory_object, key, value);
+    }
+    yyjson_mut_obj_add_val(doc, root_obj, "directories", directory_object);
+    free_search_dirs(directories, dir_total);
 
     /* Summary stats */
     yyjson_mut_obj_add_int(doc, root_obj, "total_grep_matches", gm_count);
     yyjson_mut_obj_add_int(doc, root_obj, "total_results", sr_count);
     yyjson_mut_obj_add_int(doc, root_obj, "raw_match_count", raw_count);
+    yyjson_mut_obj_add_str(doc, root_obj, "total_relation", scan_saturated ? "gte" : "eq");
+    yyjson_mut_obj_add_int(doc, root_obj, "result_offset", result_start);
+    yyjson_mut_obj_add_int(doc, root_obj, "results_returned", output_count);
+    bool has_more = result_start + output_count < sr_count;
+    yyjson_mut_obj_add_bool(doc, root_obj, "has_more", has_more);
+    if (has_more && output_count > 0) {
+        yyjson_mut_obj_add_int(doc, root_obj, "next_offset", result_start + output_count);
+    } else if (has_more) {
+        yyjson_mut_obj_add_bool(doc, root_obj,
+                                result_limit == 0 ? "result_continuation_requires_positive_limit"
+                                                  : "result_continuation_requires_higher_budget",
+                                true);
+    }
+    yyjson_mut_obj_add_int(doc, root_obj, "raw_returned", raw_output);
+    bool raw_has_more = raw_start + raw_output < raw_count;
+    yyjson_mut_obj_add_bool(doc, root_obj, "raw_has_more", raw_has_more);
+    if (raw_has_more && raw_output > 0) {
+        yyjson_mut_obj_add_int(doc, root_obj, "raw_next_offset", raw_start + raw_output);
+    } else if (raw_has_more) {
+        yyjson_mut_obj_add_bool(doc, root_obj,
+                                raw_limit == 0 ? "raw_continuation_requires_positive_limit"
+                                               : "raw_continuation_requires_higher_budget",
+                                true);
+    }
+    if (raw_content_truncated > 0) {
+        yyjson_mut_obj_add_int(doc, root_obj, "raw_content_truncated", raw_content_truncated);
+    }
+    yyjson_mut_obj_add_int(doc, root_obj, "directories_total", dir_total);
+    yyjson_mut_obj_add_int(doc, root_obj, "directories_returned", directory_output);
+    bool directories_has_more = directory_start + directory_output < dir_total;
+    yyjson_mut_obj_add_bool(doc, root_obj, "directories_has_more", directories_has_more);
+    if (directories_has_more && directory_output > 0) {
+        yyjson_mut_obj_add_int(doc, root_obj, "directory_next_offset",
+                               directory_start + directory_output);
+    } else if (directories_has_more) {
+        yyjson_mut_obj_add_bool(doc, root_obj,
+                                directory_limit == 0
+                                    ? "directory_continuation_requires_positive_limit"
+                                    : "directory_continuation_requires_higher_budget",
+                                true);
+    }
+    if (scan_saturated) {
+        yyjson_mut_obj_add_bool(doc, root_obj, "scan_saturated", true);
+    }
+    yyjson_mut_obj_add_bool(doc, root_obj, "truncated",
+                            has_more || raw_has_more || directories_has_more || scan_saturated ||
+                                budget_hit);
+    if (budget_hit) {
+        yyjson_mut_obj_add_str(doc, root_obj, "truncation_reason", "output_budget");
+    }
+    if (mode == MODE_FULL) {
+        yyjson_mut_obj_add_int(doc, root_obj, "source_max_lines_returned", source_max_lines);
+    }
     yyjson_mut_obj_add_int(doc, root_obj, "elapsed_ms", (int)elapsed_ms);
     if (sr_count > 0 && gm_count > 0) {
         char ratio[CBM_SZ_32];
@@ -9178,13 +12081,168 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
 
     char *json = yy_doc_to_str(doc);
     if (json) {
-        sanitize_ascii(json);
+        sanitize_utf8_inplace(json);
     }
     yyjson_mut_doc_free(doc);
 
-    char *result = cbm_mcp_text_result(json, false);
+    return json;
+}
+
+/* Render the same search response model in either direct JSON or the lean tree
+ * form. Compact search has a purpose-built table renderer so repeated paths
+ * and qualified-name prefixes can use the response-local directory. Full and
+ * files mode first build the canonical JSON model, then project it to tree. */
+static char *render_search_payload(search_result_t *sr, int sr_count, grep_match_t *raw,
+                                   int raw_count, int raw_content_truncated, int gm_count,
+                                   int result_start, int result_limit, int output_count,
+                                   int raw_start, int raw_output, int directory_start,
+                                   int directory_output, int raw_limit, int directory_limit,
+                                   int match_limit, int mode, int context_lines,
+                                   int source_max_lines, const char *root_path, bool scan_saturated,
+                                   bool warn_literal_pipe, uint64_t elapsed_ms, bool budget_hit,
+                                   bool json_format) {
+    if (mode == 0 && !json_format) {
+        return assemble_search_output_toon(sr, sr_count, raw, raw_count, raw_content_truncated,
+                                           gm_count, result_start, result_limit, output_count,
+                                           raw_start, raw_output, directory_start, directory_output,
+                                           raw_limit, directory_limit, match_limit, scan_saturated,
+                                           warn_literal_pipe, elapsed_ms, budget_hit, -1);
+    }
+
+    char *json = assemble_search_output(
+        sr, sr_count, raw, raw_count, raw_content_truncated, gm_count, result_start, result_limit,
+        output_count, raw_start, raw_output, directory_start, directory_output, raw_limit,
+        directory_limit, match_limit, mode, context_lines, source_max_lines, root_path,
+        scan_saturated, warn_literal_pipe, elapsed_ms, budget_hit);
+    if (!json || json_format) {
+        return json;
+    }
+    char *tree = cbm_json_to_tree(json);
     free(json);
-    return result;
+    return tree;
+}
+
+#ifdef CBM_ENABLE_TEST_SEAMS
+char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
+                                             const char *const *file_paths, int row_count,
+                                             bool json_format) {
+    if (!qualified_names || !file_paths || row_count < 0) {
+        return NULL;
+    }
+    search_result_t *results = row_count > 0 ? calloc((size_t)row_count, sizeof(*results)) : NULL;
+    if (row_count > 0 && !results) {
+        return NULL;
+    }
+    int initialized = 0;
+    for (int i = 0; i < row_count; i++) {
+        cbm_node_t node = {.id = i + SKIP_ONE,
+                           .label = "Function",
+                           .name = "synthetic",
+                           .qualified_name = qualified_names[i],
+                           .file_path = file_paths[i],
+                           .start_line = SKIP_ONE,
+                           .end_line = SKIP_ONE};
+        if (!set_search_result_identity(&results[i], &node)) {
+            free_search_results(results, initialized);
+            return NULL;
+        }
+        if (!append_search_match_line(&results[i], SKIP_ONE)) {
+            free_search_results(results, initialized + 1);
+            return NULL;
+        }
+        initialized++;
+    }
+    char *payload =
+        render_search_payload(results, row_count, NULL, 0, 0, row_count, 0, row_count, row_count, 0,
+                              0, 0, row_count, 0, row_count > 0 ? 1 : 0, row_count > 0 ? 1 : 0, 0,
+                              0, 0, "", false, false, 0, false, json_format);
+    free_search_results(results, initialized);
+    return payload;
+}
+#endif
+
+/* A pathological single qualified name, path, or source line can be larger
+ * than the caller's entire budget. Never byte-slice it: return a small,
+ * truthful floor that tells the caller how to request the omitted rows. */
+static char *search_budget_floor(int sr_count, int raw_count, int gm_count, int result_start,
+                                 int result_limit, int raw_start, int raw_limit,
+                                 int directory_start, int directory_limit, int directory_total,
+                                 bool scan_saturated, bool json_format, int max_output_tokens) {
+    (void)gm_count;
+    (void)max_output_tokens;
+    bool result_has_more = result_start < sr_count;
+    bool raw_has_more = raw_start < raw_count;
+    bool directories_has_more = directory_start < directory_total;
+    if (!json_format) {
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        cbm_tree_scalar_int(&sb, "total_results", sr_count);
+        cbm_tree_scalar_int(&sb, "raw_match_count", raw_count);
+        cbm_tree_scalar_int(&sb, "result_offset", result_start);
+        cbm_tree_scalar_int(&sb, "results_returned", 0);
+        cbm_tree_scalar_bool(&sb, "has_more", result_has_more);
+        if (result_has_more) {
+            cbm_tree_scalar_bool(&sb,
+                                 result_limit == 0 ? "result_continuation_requires_positive_limit"
+                                                   : "result_continuation_requires_higher_budget",
+                                 true);
+        }
+        cbm_tree_scalar_int(&sb, "raw_offset", raw_start);
+        cbm_tree_scalar_int(&sb, "raw_returned", 0);
+        cbm_tree_scalar_bool(&sb, "raw_has_more", raw_has_more);
+        if (raw_has_more && raw_limit == 0) {
+            cbm_tree_scalar_bool(&sb, "raw_continuation_requires_positive_limit", true);
+        }
+        cbm_tree_scalar_int(&sb, "directories_total", directory_total);
+        cbm_tree_scalar_int(&sb, "directory_offset", directory_start);
+        cbm_tree_scalar_int(&sb, "directories_returned", 0);
+        cbm_tree_scalar_bool(&sb, "directories_has_more", directories_has_more);
+        if (directories_has_more && directory_limit == 0) {
+            cbm_tree_scalar_bool(&sb, "directory_continuation_requires_positive_limit", true);
+        }
+        if (scan_saturated) {
+            cbm_tree_scalar_bool(&sb, "scan_saturated", true);
+        }
+        cbm_tree_scalar_bool(&sb, "truncated", true);
+        cbm_tree_scalar_str(&sb, "truncation_reason", "output_budget");
+        return cbm_sb_finish(&sb);
+    }
+
+    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *root = yyjson_mut_obj(doc);
+    yyjson_mut_doc_set_root(doc, root);
+    yyjson_mut_obj_add_int(doc, root, "total_results", sr_count);
+    yyjson_mut_obj_add_int(doc, root, "raw_match_count", raw_count);
+    yyjson_mut_obj_add_int(doc, root, "result_offset", result_start);
+    yyjson_mut_obj_add_int(doc, root, "results_returned", 0);
+    yyjson_mut_obj_add_bool(doc, root, "has_more", result_has_more);
+    if (result_has_more) {
+        yyjson_mut_obj_add_bool(doc, root,
+                                result_limit == 0 ? "result_continuation_requires_positive_limit"
+                                                  : "result_continuation_requires_higher_budget",
+                                true);
+    }
+    yyjson_mut_obj_add_int(doc, root, "raw_offset", raw_start);
+    yyjson_mut_obj_add_int(doc, root, "raw_returned", 0);
+    yyjson_mut_obj_add_bool(doc, root, "raw_has_more", raw_has_more);
+    if (raw_has_more && raw_limit == 0) {
+        yyjson_mut_obj_add_bool(doc, root, "raw_continuation_requires_positive_limit", true);
+    }
+    yyjson_mut_obj_add_int(doc, root, "directories_total", directory_total);
+    yyjson_mut_obj_add_int(doc, root, "directory_offset", directory_start);
+    yyjson_mut_obj_add_int(doc, root, "directories_returned", 0);
+    yyjson_mut_obj_add_bool(doc, root, "directories_has_more", directories_has_more);
+    if (directories_has_more && directory_limit == 0) {
+        yyjson_mut_obj_add_bool(doc, root, "directory_continuation_requires_positive_limit", true);
+    }
+    if (scan_saturated) {
+        yyjson_mut_obj_add_bool(doc, root, "scan_saturated", true);
+    }
+    yyjson_mut_obj_add_bool(doc, root, "truncated", true);
+    yyjson_mut_obj_add_str(doc, root, "truncation_reason", "output_budget");
+    char *json = yy_doc_to_str(doc);
+    yyjson_mut_doc_free(doc);
+    return json;
 }
 
 /* Read grep output from fp, parse file:line:content format, apply path filter,
@@ -9201,62 +12259,138 @@ static const char *strip_root_prefix(const char *path, const char *root, size_t
     return p;
 }
 
-static grep_match_t *collect_grep_matches(FILE *fp, const char *root_path, size_t root_len,
-                                          bool has_path_filter, cbm_regex_t *path_regex,
-                                          int grep_limit, int *out_count) {
-    int gm_cap = CBM_SZ_64;
-    int gm_count = 0;
-    grep_match_t *gm = malloc(gm_cap * sizeof(grep_match_t));
-    char line[CBM_SZ_2K];
-
-    while (fgets(line, sizeof(line), fp) && gm_count < grep_limit) {
-        size_t len = strlen(line);
-        while (len > 0 && (line[len - SKIP_ONE] == '\n' || line[len - SKIP_ONE] == '\r')) {
-            line[--len] = '\0';
-        }
-        if (len == 0) {
-            continue;
+static bool search_match_bounds(const char *content, const char *pattern, bool use_regex,
+                                const cbm_regex_t *compiled_regex, size_t *start_out,
+                                size_t *end_out) {
+    if (!content || !pattern || !start_out || !end_out) {
+        return false;
+    }
+    if (!use_regex) {
+        const char *match = strstr(content, pattern);
+        if (!match) {
+            return false;
         }
+        *start_out = (size_t)(match - content);
+        *end_out = *start_out + strlen(pattern);
+        return true;
+    }
+    if (!compiled_regex) {
+        return false;
+    }
+    cbm_regmatch_t match = {.rm_so = -1, .rm_eo = -1};
+    if (cbm_regexec(compiled_regex, content, 1, &match, 0) != CBM_REG_OK || match.rm_so < 0 ||
+        match.rm_eo < match.rm_so) {
+        return false;
+    }
+    *start_out = (size_t)match.rm_so;
+    *end_out = (size_t)match.rm_eo;
+    return true;
+}
 
-        /* PowerShell output uses tab as delimiter (paths may contain colons
-         * on Windows, e.g. C:\dir\file). Unix grep uses colon. */
-#ifdef _WIN32
-        char sep = '\t';
-#else
-        char sep = ':';
-#endif
-        char *sep1 = strchr(line, (unsigned char)sep);
-        if (!sep1) {
+static bool search_utf8_continuation_byte(unsigned char byte) {
+    return (byte & 0xC0U) == 0x80U;
+}
+
+/* A continuation-shaped byte is not necessarily part of valid UTF-8. Adjust
+ * paging only when a complete sequence actually spans the requested boundary;
+ * malformed bytes remain independently addressable original source bytes. */
+static size_t search_utf8_page_start(const char *content, size_t total, size_t start) {
+    if (start >= total || !search_utf8_continuation_byte((unsigned char)content[start])) {
+        return start;
+    }
+    size_t earliest = start > 3U ? start - 3U : 0U;
+    for (size_t candidate = start; candidate > earliest;) {
+        candidate--;
+        if (search_utf8_continuation_byte((unsigned char)content[candidate])) {
             continue;
         }
-        char *sep2 = strchr(sep1 + SKIP_ONE, (unsigned char)sep);
-        if (!sep2) {
-            continue;
+        size_t sequence = utf8_sequence_len((const unsigned char *)content + candidate,
+                                            (const unsigned char *)content + total);
+        if (sequence > 1U && candidate + sequence > start) {
+            return candidate + sequence;
         }
-        *sep1 = '\0';
-        *sep2 = '\0';
-
-#ifdef _WIN32
-        cbm_normalize_path_sep(line);
-#endif
-        const char *path = line;
-        const char *file = strip_root_prefix(path, root_path, root_len);
+        break;
+    }
+    return start;
+}
 
-        if (has_path_filter && cbm_regexec(path_regex, file, 0, NULL, 0) != CBM_REG_OK) {
+static size_t search_utf8_page_end(const char *content, size_t total, size_t end) {
+    if (end >= total || !search_utf8_continuation_byte((unsigned char)content[end])) {
+        return end;
+    }
+    size_t earliest = end > 3U ? end - 3U : 0U;
+    for (size_t candidate = end; candidate > earliest;) {
+        candidate--;
+        if (search_utf8_continuation_byte((unsigned char)content[candidate])) {
             continue;
         }
+        size_t sequence = utf8_sequence_len((const unsigned char *)content + candidate,
+                                            (const unsigned char *)content + total);
+        if (sequence > 1U && candidate + sequence > end) {
+            return candidate;
+        }
+        break;
+    }
+    return end;
+}
+
+/* Select one bounded raw-line preview. By default it contains the complete
+ * match whenever the match itself fits. An explicit content offset pages the
+ * original line independently of the raw-row cursor. Boundaries inside valid
+ * UTF-8 code points are adjusted and reported; malformed bytes remain exactly
+ * addressable and are reversibly encoded by the shared output boundary. */
+static void search_raw_preview(grep_match_t *match, const char *content,
+                               bool raw_content_offset_set, size_t raw_content_offset,
+                               bool match_known, size_t match_start, size_t match_end) {
+    const size_t preview_capacity = sizeof(match->content) - SKIP_ONE;
+    size_t total = strlen(content);
+    size_t start = 0;
+    if (raw_content_offset_set) {
+        start = raw_content_offset < total ? raw_content_offset : total;
+    } else if (match_known && total > preview_capacity) {
+        size_t match_length = match_end - match_start;
+        if (match_length >= preview_capacity) {
+            start = match_start;
+        } else {
+            size_t lead = (preview_capacity - match_length) / 2U;
+            start = match_start > lead ? match_start - lead : 0;
+            if (start + preview_capacity > total) {
+                start = total - preview_capacity;
+            }
+        }
+    }
+    start = search_utf8_page_start(content, total, start);
 
-        safe_grow(gm, gm_count, gm_cap, PAIR_LEN);
-        snprintf(gm[gm_count].file, sizeof(gm[0].file), "%s", file);
-        gm[gm_count].line = (int)strtol(sep1 + SKIP_ONE, NULL, CBM_DECIMAL_BASE);
-        snprintf(gm[gm_count].content, sizeof(gm[0].content), "%s", sep2 + SKIP_ONE);
-        sanitize_ascii(gm[gm_count].content);
-        gm_count++;
+    size_t remaining = total - start;
+    size_t returned = remaining < preview_capacity ? remaining : preview_capacity;
+    size_t end = start + returned;
+    if (end < total) {
+        end = search_utf8_page_end(content, total, end);
     }
+    returned = end - start;
+    memcpy(match->content, content + start, returned);
+    match->content[returned] = '\0';
+    match->content_start_byte = start;
+    match->content_returned_bytes = returned;
+    match->content_total_bytes = total;
+    match->match_start_byte = match_start;
+    match->match_end_byte = match_end;
+    match->match_known = match_known;
+    match->content_truncated = start > 0 || end < total;
+}
 
-    *out_count = gm_count;
-    return gm;
+#ifdef CBM_ENABLE_TEST_SEAMS
+char *cbm_mcp_render_raw_preview_for_testing(const char *content, bool content_offset_set,
+                                             size_t content_offset, bool json_format) {
+    if (!content) {
+        return NULL;
+    }
+    grep_match_t raw = {.file = "fixture.raw", .line = 7};
+    search_raw_preview(&raw, content, content_offset_set, content_offset, false, 0, 0);
+    return render_search_payload(NULL, 0, &raw, 1, raw.content_truncated ? 1 : 0, 1, 0, 0, 0, 0, 1,
+                                 0, 0, 1, 0, 0, 0, 0, 0, "", false, false, 0, false, json_format);
 }
+#endif
 
 /* Find the tightest node containing a line in a file. Returns index or -1. */
 static int find_tightest_node(cbm_node_t *nodes, int count, int line) {
@@ -9265,7 +12399,14 @@ static int find_tightest_node(cbm_node_t *nodes, int count, int line) {
     for (int j = 0; j < count; j++) {
         if (nodes[j].start_line <= line && nodes[j].end_line >= line) {
             int span = nodes[j].end_line - nodes[j].start_line;
-            if (span < best_span) {
+            const char *candidate_qn = nodes[j].qualified_name ? nodes[j].qualified_name : "";
+            const char *best_qn =
+                best >= 0 && nodes[best].qualified_name ? nodes[best].qualified_name : "";
+            bool stable_tie_winner =
+                span == best_span &&
+                (best < 0 || strcmp(candidate_qn, best_qn) < 0 ||
+                 (strcmp(candidate_qn, best_qn) == 0 && nodes[j].id < nodes[best].id));
+            if (span < best_span || stable_tie_winner) {
                 best = j;
                 best_span = span;
             }
@@ -9274,52 +12415,127 @@ static int find_tightest_node(cbm_node_t *nodes, int count, int line) {
     return best;
 }
 
+static bool set_search_result_identity(search_result_t *result, const cbm_node_t *node) {
+    result->qualified_name = heap_strdup(node->qualified_name ? node->qualified_name : "");
+    result->file = heap_strdup(node->file_path ? node->file_path : "");
+    if (!result->qualified_name || !result->file) {
+        free(result->qualified_name);
+        free(result->file);
+        result->qualified_name = NULL;
+        result->file = NULL;
+        return false;
+    }
+    result->node_id = node->id;
+    snprintf(result->node_name, sizeof(result->node_name), "%s", node->name ? node->name : "");
+    snprintf(result->label, sizeof(result->label), "%s", node->label ? node->label : "");
+    result->start_line = node->start_line;
+    result->end_line = node->end_line;
+    return true;
+}
+
+static bool append_search_match_line(search_result_t *result, int line) {
+    enum { SEARCH_MATCH_LINES_RETAINED = 500 };
+    if (result->match_count == INT_MAX) {
+        return false;
+    }
+    result->match_count++;
+    if (result->match_stored_count >= SEARCH_MATCH_LINES_RETAINED) {
+        return true;
+    }
+    if (result->match_stored_count >= result->match_capacity) {
+        int next_capacity = result->match_capacity > 0 ? result->match_capacity * PAIR_LEN : 8;
+        if (next_capacity > SEARCH_MATCH_LINES_RETAINED) {
+            next_capacity = SEARCH_MATCH_LINES_RETAINED;
+        }
+        if (next_capacity < result->match_capacity ||
+            (size_t)next_capacity > SIZE_MAX / sizeof(*result->match_lines)) {
+            return false;
+        }
+        int *grown = realloc(result->match_lines, (size_t)next_capacity * sizeof(*grown));
+        if (!grown) {
+            return false;
+        }
+        result->match_lines = grown;
+        result->match_capacity = next_capacity;
+    }
+    result->match_lines[result->match_stored_count++] = line;
+    return true;
+}
+
 /* Add a grep hit to the search result set (merge into existing or create new). */
-static void add_to_search_results(search_result_t **sr, int *sr_count, int *sr_cap, cbm_node_t *n,
+static bool add_to_search_results(search_result_t **sr, int *sr_count, int *sr_cap, cbm_node_t *n,
                                   int line) {
     for (int j = 0; j < *sr_count; j++) {
         if ((*sr)[j].node_id == n->id) {
-            if ((*sr)[j].match_count < CBM_SZ_64) {
-                (*sr)[j].match_lines[(*sr)[j].match_count++] = line;
-            }
-            return;
+            return append_search_match_line(&(*sr)[j], line);
         }
     }
     if (*sr_count >= *sr_cap) {
-        *sr_cap *= PAIR_LEN;
-        *sr = safe_realloc(*sr, *sr_cap * sizeof(search_result_t));
-        memset(&(*sr)[*sr_count], 0, (*sr_cap - *sr_count) * sizeof(search_result_t));
+        int next_capacity = *sr_cap * PAIR_LEN;
+        search_result_t *grown = realloc(*sr, (size_t)next_capacity * sizeof(**sr));
+        if (!grown) {
+            return false;
+        }
+        memset(grown + *sr_cap, 0, (size_t)(next_capacity - *sr_cap) * sizeof(*grown));
+        *sr = grown;
+        *sr_cap = next_capacity;
     }
     search_result_t *r = &(*sr)[*sr_count];
-    r->node_id = n->id;
-    snprintf(r->node_name, sizeof(r->node_name), "%s", n->name ? n->name : "");
-    snprintf(r->qualified_name, sizeof(r->qualified_name), "%s",
-             n->qualified_name ? n->qualified_name : "");
-    snprintf(r->label, sizeof(r->label), "%s", n->label ? n->label : "");
-    snprintf(r->file, sizeof(r->file), "%s", n->file_path ? n->file_path : "");
-    r->start_line = n->start_line;
-    r->end_line = n->end_line;
-    r->match_lines[0] = line;
-    r->match_count = SKIP_ONE;
+    if (!set_search_result_identity(r, n)) {
+        return false;
+    }
+    if (!append_search_match_line(r, line)) {
+        free(r->qualified_name);
+        free(r->file);
+        r->qualified_name = NULL;
+        r->file = NULL;
+        return false;
+    }
     (*sr_count)++;
+    return true;
 }
 
 /* Match a single grep hit to the tightest containing node, then add to sr or raw. */
-static void classify_grep_hit(grep_match_t *hit, cbm_node_t *file_nodes, int file_node_count,
+static bool classify_grep_hit(grep_match_t *hit, cbm_node_t *file_nodes, int file_node_count,
                               search_result_t **sr, int *sr_count, int *sr_cap, grep_match_t **raw,
-                              int *raw_count, int *raw_cap) {
+                              int raw_offset, int raw_limit, int *raw_count, int *raw_stored_count,
+                              int *raw_cap, int *raw_content_truncated) {
     int best = find_tightest_node(file_nodes, file_node_count, hit->line);
     if (best >= 0) {
-        add_to_search_results(sr, sr_count, sr_cap, &file_nodes[best], hit->line);
+        return add_to_search_results(sr, sr_count, sr_cap, &file_nodes[best], hit->line);
     } else {
-        if (*raw_count >= *raw_cap) {
-            *raw_cap = (*raw_cap == 0) ? CBM_SZ_32 : *raw_cap * PAIR_LEN;
-            *raw = safe_realloc(*raw, *raw_cap * sizeof(grep_match_t));
+        if (*raw_count == INT_MAX) {
+            return false;
+        }
+        int raw_index = (*raw_count)++;
+        if (hit->content_truncated) {
+            if (*raw_content_truncated == INT_MAX) {
+                return false;
+            }
+            (*raw_content_truncated)++;
+        }
+        bool retain =
+            raw_limit > 0 && raw_index >= raw_offset && raw_index - raw_offset < raw_limit;
+        if (!retain) {
+            return true;
         }
-        if (*raw) {
-            (*raw)[(*raw_count)++] = *hit;
+        if (*raw_stored_count >= *raw_cap) {
+            int next_capacity = (*raw_cap == 0) ? 8 : *raw_cap * PAIR_LEN;
+            if (next_capacity > raw_limit) {
+                next_capacity = raw_limit;
+            }
+            grep_match_t *grown = realloc(*raw, (size_t)next_capacity * sizeof(**raw));
+            if (!grown) {
+                return false;
+            }
+            *raw = grown;
+            *raw_cap = next_capacity;
         }
+        (*raw)[*raw_stored_count] = *hit;
+        hit->file = NULL;
+        (*raw_stored_count)++;
     }
+    return true;
 }
 
 /* Free a file_nodes array returned from cbm_store_find_nodes_by_file. */
@@ -9335,34 +12551,123 @@ static void free_file_nodes(cbm_node_t *nodes, int count) {
     free(nodes);
 }
 
-/* Classify all grep matches file-by-file into search results and raw hits. */
-static void classify_all_grep_hits(grep_match_t *gm, int gm_count, cbm_store_t *store,
-                                   const char *project, search_result_t **sr, int *sr_count,
-                                   int *sr_cap, grep_match_t **raw, int *raw_count, int *raw_cap) {
-    qsort(gm, gm_count, sizeof(grep_match_t), (int (*)(const void *, const void *))strcmp);
-    int i = 0;
-    while (i < gm_count) {
-        const char *cur_file = gm[i].file;
-        int file_start = i;
-        while (i < gm_count && strcmp(gm[i].file, cur_file) == 0) {
-            i++;
+/* Parse and classify the complete grep stream without retaining one object per
+ * hit. Graph results retain one identity per distinct node plus at most 500
+ * line numbers each; raw matches retain only the caller's requested page.
+ * Exact totals are counted while the stream is consumed to EOF. */
+static bool scan_and_classify_grep_matches(
+    FILE *fp, const char *root_path, size_t root_len, bool has_path_filter, cbm_regex_t *path_regex,
+    const char *pattern, bool use_regex, bool raw_content_offset_set, size_t raw_content_offset,
+    cbm_store_t *store, const char *project, search_result_t **sr, int *sr_count, int *sr_cap,
+    grep_match_t **raw, int raw_offset, int raw_limit, int *raw_count, int *raw_stored_count,
+    int *raw_cap, int *raw_content_truncated, int *grep_count) {
+    char *line = NULL;
+    size_t line_capacity = 0;
+    char *current_file = NULL;
+    cbm_node_t *file_nodes = NULL;
+    int file_node_count = 0;
+    cbm_regex_t content_regex;
+    bool content_regex_ready = use_regex && pattern &&
+                               cbm_regcomp(&content_regex, pattern, CBM_REG_EXTENDED) == CBM_REG_OK;
+    bool ok = true;
+
+    for (;;) {
+        ssize_t line_length = cbm_getline(&line, &line_capacity, fp);
+        if (line_length < 0) {
+            if (!feof(fp)) {
+                ok = false;
+            }
+            break;
+        }
+        size_t len = (size_t)line_length;
+        while (len > 0 && (line[len - SKIP_ONE] == '\n' || line[len - SKIP_ONE] == '\r')) {
+            line[--len] = '\0';
+        }
+        if (len == 0) {
+            continue;
+        }
+
+#ifdef _WIN32
+        char sep = '\t';
+#else
+        char sep = ':';
+#endif
+        char *sep1 = strchr(line, (unsigned char)sep);
+        if (!sep1) {
+            continue;
+        }
+        char *sep2 = strchr(sep1 + SKIP_ONE, (unsigned char)sep);
+        if (!sep2) {
+            continue;
+        }
+        *sep1 = '\0';
+        *sep2 = '\0';
+#ifdef _WIN32
+        cbm_normalize_path_sep(line);
+#endif
+        const char *file = strip_root_prefix(line, root_path, root_len);
+        if (has_path_filter && cbm_regexec(path_regex, file, 0, NULL, 0) != CBM_REG_OK) {
+            continue;
+        }
+        if (*grep_count == INT_MAX) {
+            ok = false;
+            break;
+        }
+        (*grep_count)++;
+
+        if (!current_file || strcmp(current_file, file) != 0) {
+            free_file_nodes(file_nodes, file_node_count);
+            file_nodes = NULL;
+            file_node_count = 0;
+            free(current_file);
+            current_file = heap_strdup(file);
+            if (!current_file) {
+                ok = false;
+                break;
+            }
+            if (store) {
+                (void)cbm_store_find_nodes_by_file(store, project, file, &file_nodes,
+                                                   &file_node_count);
+            }
         }
-        cbm_node_t *file_nodes = NULL;
-        int file_node_count = 0;
-        if (store) {
-            cbm_store_find_nodes_by_file(store, project, cur_file, &file_nodes, &file_node_count);
+
+        grep_match_t hit = {0};
+        hit.file = heap_strdup(file);
+        if (!hit.file) {
+            ok = false;
+            break;
         }
-        for (int mi = file_start; mi < i; mi++) {
-            classify_grep_hit(&gm[mi], file_nodes, file_node_count, sr, sr_count, sr_cap, raw,
-                              raw_count, raw_cap);
+        hit.line = (int)strtol(sep1 + SKIP_ONE, NULL, CBM_DECIMAL_BASE);
+        const char *content = sep2 + SKIP_ONE;
+        size_t match_start = 0;
+        size_t match_end = 0;
+        bool match_known = search_match_bounds(content, pattern, use_regex,
+                                               content_regex_ready ? &content_regex : NULL,
+                                               &match_start, &match_end);
+        search_raw_preview(&hit, content, raw_content_offset_set, raw_content_offset, match_known,
+                           match_start, match_end);
+        if (!classify_grep_hit(&hit, file_nodes, file_node_count, sr, sr_count, sr_cap, raw,
+                               raw_offset, raw_limit, raw_count, raw_stored_count, raw_cap,
+                               raw_content_truncated)) {
+            free(hit.file);
+            ok = false;
+            break;
         }
-        free_file_nodes(file_nodes, file_node_count);
+        free(hit.file);
+    }
+
+    if (content_regex_ready) {
+        cbm_regfree(&content_regex);
     }
+    free_file_nodes(file_nodes, file_node_count);
+    free(current_file);
+    free(line);
+    return ok;
 }
 
 /* Write indexed file list for scoped grep. Returns true if scoped.
  * When a path_filter is provided, apply it here — before grep — so large
- * indexed projects do not scan files only for collect_grep_matches to discard
+ * indexed projects do not scan files only for the stream classifier to discard
  * them later. The predicate is IDENTICAL to the post-grep filter: the same
  * compiled regex run against the same root-relative path (separators
  * normalized on Windows first), so prefiltering can only skip files whose
@@ -9374,8 +12679,8 @@ static void classify_all_grep_hits(grep_match_t *gm, int gm_count, cbm_store_t *
  * created inside the private scratch directory; this function never opens or
  * closes it, so the list is never reachable through a predictable pathname. */
 static bool write_scoped_filelist(cbm_mcp_server_t *srv, const char *project, const char *root_path,
-                                  FILE *fl, bool has_path_filter, cbm_regex_t *path_regex,
-                                  int *out_written) {
+                                  const char *file_pattern, FILE *fl, bool has_path_filter,
+                                  cbm_regex_t *path_regex, int *out_written) {
     *out_written = 0;
     cbm_store_t *pre_store = resolve_store(srv, project);
     if (!pre_store) {
@@ -9383,8 +12688,13 @@ static bool write_scoped_filelist(cbm_mcp_server_t *srv, const char *project, co
     }
     char **indexed_files = NULL;
     int indexed_count = 0;
-    if (cbm_store_list_files(pre_store, project, &indexed_files, &indexed_count) != CBM_STORE_OK ||
-        indexed_count == 0) {
+    if (cbm_store_list_files(pre_store, project, &indexed_files, &indexed_count) != CBM_STORE_OK) {
+        return false;
+    }
+    if (indexed_count == 0) {
+        /* cbm_store_list_files owns an allocation even for an empty successful
+         * result; no element loop below can release that outer array. */
+        free(indexed_files);
         return false;
     }
     bool ok = false;
@@ -9407,6 +12717,17 @@ static bool write_scoped_filelist(cbm_mcp_server_t *srv, const char *project, co
                     continue;
                 }
             }
+#ifndef _WIN32
+            /* GNU grep's --include is unavailable in BusyBox grep. Filter the
+             * canonical list before xargs instead, preserving grep's basename
+             * glob semantics without making the shipped static binary depend
+             * on GNU userland. Windows keeps its PowerShell -like filter. */
+            const char *basename = strrchr(indexed_files[fi], '/');
+            basename = basename ? basename + SKIP_ONE : indexed_files[fi];
+            if (file_pattern && fnmatch(file_pattern, basename, 0) != 0) {
+                continue;
+            }
+#endif
             /* Write "<root>/<file>" piece-by-piece (no fixed-size buffer, so an
              * arbitrarily long absolute path cannot overflow). Forward slash join
              * so xargs doesn't treat Windows backslashes as escapes; binary mode
@@ -9633,15 +12954,17 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     char *file_pattern = cbm_mcp_get_string_arg(args, "file_pattern");
     char *path_filter = cbm_mcp_get_string_arg(args, "path_filter");
     char *mode_str = cbm_mcp_get_string_arg(args, "mode");
-    int limit = cbm_mcp_get_int_arg(args, "limit", MCP_DEFAULT_LIMIT);
+    int legacy_limit = cbm_mcp_get_int_arg(args, "limit", MCP_DEFAULT_LIMIT);
     /* #1511: a negative limit flowed straight into the result cap and came back
      * as the reported count ("results: -5"), which reads to an agent as a real
      * answer rather than a rejected argument. The schema now declares
      * minimum:1, but a schema is a request to the client, never a guarantee to
      * the server — clamp here too. */
-    if (limit < 1) {
-        limit = MCP_DEFAULT_LIMIT;
+    if (legacy_limit < 1) {
+        legacy_limit = MCP_DEFAULT_LIMIT;
     }
+    int result_limit = cbm_mcp_get_int_arg(args, "result_limit", legacy_limit);
+    int result_offset = cbm_mcp_get_int_arg(args, "result_offset", 0);
     int context_lines = cbm_mcp_get_int_arg(args, "context", 0);
     bool use_regex = cbm_mcp_get_bool_arg(args, "regex");
     uint64_t search_t0 = cbm_now_ms();
@@ -9652,6 +12975,71 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     int mode = parse_search_mode(mode_str);
     free(mode_str);
 
+    if (result_limit < 1) {
+        result_limit = MCP_DEFAULT_LIMIT;
+    } else if (result_limit > 500) {
+        result_limit = 500;
+    }
+    if (result_offset < 0) {
+        result_offset = 0;
+    }
+    int raw_limit = cbm_mcp_get_int_arg(args, "raw_limit", 5);
+    if (raw_limit < 0) {
+        raw_limit = 0;
+    } else if (raw_limit > 100) {
+        raw_limit = 100;
+    }
+    int raw_offset = cbm_mcp_get_int_arg(args, "raw_offset", 0);
+    if (raw_offset < 0) {
+        raw_offset = 0;
+    }
+    int raw_content_offset_arg = cbm_mcp_get_int_arg(args, "raw_content_offset", 0);
+    if (raw_content_offset_arg < 0) {
+        raw_content_offset_arg = 0;
+    }
+    bool raw_content_offset_set = false;
+    yyjson_doc *search_args_doc = args ? yyjson_read(args, strlen(args), 0) : NULL;
+    yyjson_val *search_args_root = search_args_doc ? yyjson_doc_get_root(search_args_doc) : NULL;
+    yyjson_val *raw_content_offset_val =
+        search_args_root && yyjson_is_obj(search_args_root)
+            ? yyjson_obj_get(search_args_root, "raw_content_offset")
+            : NULL;
+    raw_content_offset_set = raw_content_offset_val && yyjson_is_int(raw_content_offset_val);
+    yyjson_doc_free(search_args_doc);
+    int directory_limit = cbm_mcp_get_int_arg(args, "directory_limit", 20);
+    if (directory_limit < 0) {
+        directory_limit = 0;
+    } else if (directory_limit > 64) {
+        directory_limit = 64;
+    }
+    int directory_offset = cbm_mcp_get_int_arg(args, "directory_offset", 0);
+    if (directory_offset < 0) {
+        directory_offset = 0;
+    }
+    int match_limit = cbm_mcp_get_int_arg(args, "match_limit", 8);
+    if (match_limit < 1) {
+        match_limit = 1;
+    } else if (match_limit > 500) {
+        match_limit = 500;
+    }
+    int source_max_lines = cbm_mcp_get_int_arg(args, "source_max_lines", 20);
+    if (source_max_lines < 1) {
+        source_max_lines = 1;
+    } else if (source_max_lines > 200) {
+        source_max_lines = 200;
+    }
+    /* Full source is an explicit detail request and gets a larger default;
+     * compact/files stay lean. Every mode still has an exact serialized-byte
+     * ceiling, and callers can raise it deliberately. */
+    int max_output_tokens =
+        cbm_mcp_get_int_arg(args, "max_output_tokens", mode == 1 ? 12000 : 3200);
+    if (max_output_tokens < 128) {
+        max_output_tokens = 128;
+    } else if (max_output_tokens > 1000000) {
+        max_output_tokens = 1000000;
+    }
+    size_t byte_budget = (size_t)max_output_tokens * (size_t)MCP_OUTPUT_BYTES_PER_TOKEN_ESTIMATE;
+
     cbm_regex_t path_regex;
     bool has_path_filter = compile_path_filter(path_filter, &path_regex);
     free(path_filter);
@@ -9767,12 +13155,6 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     const char *tmpfile = scratch.pattern_path;
     const char *filelist = scratch.filelist_path;
 
-    /* No grep-level match limit — let grep find all matches, then dedup and
-     * cap in our code. The -m flag caused results from large vendored files
-     * to exhaust the quota before reaching project source files. */
-    enum { GREP_MAX_MATCHES = 500 };
-    int grep_limit = GREP_MAX_MATCHES;
-
     /* Scope grep to indexed files only — avoids scanning vendored/generated code.
      * Query the graph for distinct file paths, write them to a temp file,
      * then use xargs to pass them to grep. Falls back to recursive grep if
@@ -9780,25 +13162,36 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     bool scoped = false;
     int scoped_written = 0;
 
-    scoped = write_scoped_filelist(srv, project, root_path, scratch.filelist, has_path_filter,
-                                   has_path_filter ? &path_regex : NULL, &scoped_written);
+    scoped = write_scoped_filelist(srv, project, root_path, file_pattern, scratch.filelist,
+                                   has_path_filter, has_path_filter ? &path_regex : NULL,
+                                   &scoped_written);
     /* Close before grep runs: this is what flushes the records the helper wrote
      * through the descriptor. Clearing the field hands ownership to
      * search_scratch_close, which still unlinks the file itself. */
     (void)fclose(scratch.filelist);
     scratch.filelist = NULL;
 
-    /* Collect grep matches into array */
+    /* Consume and classify the complete stream. Only graph identities, bounded
+     * per-result line evidence, and the requested raw page are retained. */
+    cbm_store_t *store = resolve_store(srv, project);
+    int sr_cap = CBM_SZ_32;
+    int sr_count = 0;
+    search_result_t *sr = calloc((size_t)sr_cap, sizeof(*sr));
+    int raw_cap = 0;
+    int raw_count = 0;
+    int raw_stored_count = 0;
+    int raw_content_truncated = 0;
+    grep_match_t *raw = NULL;
     int gm_count = 0;
-    grep_match_t *gm = NULL;
+    bool scan_saturated = false;
+    bool scan_ok = sr != NULL;
     if (scoped && scoped_written == 0) {
-        /* The path_filter excluded every indexed file — nothing to scan.
+        /* The path_filter (or POSIX file_pattern) excluded every indexed file — nothing to scan.
          * Skip the grep subprocess: xargs on an empty filelist is
          * platform-dependent (GNU execs grep once with no operands, BSD
          * skips), and the post-grep filter would drop every hit anyway. */
-        gm = malloc(sizeof(grep_match_t)); /* empty set; freed below */
         search_scratch_close(&scratch);
-    } else {
+    } else if (scan_ok) {
         char cmd[CBM_SZ_4K];
         build_grep_cmd(cmd, sizeof(cmd), use_regex, scoped, file_pattern, tmpfile, filelist,
                        root_path);
@@ -9806,6 +13199,7 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         FILE *fp = cbm_popen(cmd, "r");
         if (!fp) {
             search_scratch_close(&scratch);
+            free_search_results(sr, sr_count);
             free(root_path);
             free(pattern);
             free(project);
@@ -9813,39 +13207,54 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
             return cbm_mcp_text_result("search failed", true);
         }
 
-        gm = collect_grep_matches(fp, root_path, strlen(root_path), has_path_filter, &path_regex,
-                                  grep_limit, &gm_count);
-        cbm_pclose(fp);
+        scan_ok = scan_and_classify_grep_matches(
+            fp, root_path, strlen(root_path), has_path_filter, &path_regex, pattern, use_regex,
+            raw_content_offset_set, (size_t)raw_content_offset_arg, store, project, &sr, &sr_count,
+            &sr_cap, &raw, raw_offset, raw_limit, &raw_count, &raw_stored_count, &raw_cap,
+            &raw_content_truncated, &gm_count);
+        int close_status = cbm_pclose(fp);
+        scan_ok = scan_ok && search_subprocess_succeeded(close_status);
         /* Both scratch files and the private directory go here — unlike the old
          * code, the file list is removed even when the scan was not scoped. */
         search_scratch_close(&scratch);
     }
 
-    /* ── Phase 2+3: Block expansion + graph ranking ──────────── */
-    /* Sort grep matches by file for contiguous processing.
-     * Then: one SQL query per unique file for nodes, one batch query for all degrees. */
-
-    cbm_store_t *store = resolve_store(srv, project);
-
-    int sr_cap = CBM_SZ_32;
-    int sr_count = 0;
-    search_result_t *sr = calloc(sr_cap, sizeof(search_result_t));
-
-    int raw_cap = CBM_SZ_32;
-    int raw_count = 0;
-    grep_match_t *raw = malloc(raw_cap * sizeof(grep_match_t));
-
-    /* Sort matches by file path for contiguous per-file processing */
-    qsort(gm, gm_count, sizeof(grep_match_t), (int (*)(const void *, const void *))strcmp);
-
-    classify_all_grep_hits(gm, gm_count, store, project, &sr, &sr_count, &sr_cap, &raw, &raw_count,
-                           &raw_cap);
+    if (!scan_ok) {
+        search_scratch_close(&scratch);
+        free_search_results(sr, sr_count);
+        free_grep_matches(raw, raw_stored_count);
+        free(root_path);
+        free(pattern);
+        free(project);
+        free(file_pattern);
+        if (has_path_filter) {
+            cbm_regfree(&path_regex);
+        }
+        return cbm_mcp_text_result("search failed before the complete result set was scanned",
+                                   true);
+    }
 
+    /* ── Phase 2+3: degree expansion + global graph ranking ─── */
     /* Phase 3: batch degree query — ONE query for all results instead of 2×N */
     if (store && sr_count > 0) {
         int64_t *ids = malloc(sr_count * sizeof(int64_t));
         int *in_degs = malloc(sr_count * sizeof(int));
         int *out_degs = malloc(sr_count * sizeof(int));
+        if (!ids || !in_degs || !out_degs) {
+            free(ids);
+            free(in_degs);
+            free(out_degs);
+            free_search_results(sr, sr_count);
+            free_grep_matches(raw, raw_stored_count);
+            free(root_path);
+            free(pattern);
+            free(project);
+            free(file_pattern);
+            if (has_path_filter) {
+                cbm_regfree(&path_regex);
+            }
+            return cbm_mcp_text_result("out of memory", true);
+        }
         for (int j = 0; j < sr_count; j++) {
             ids[j] = sr[j].node_id;
         }
@@ -9871,28 +13280,151 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
 
     /* ── Phase 4: Context assembly (extracted helper) ─────────── */
 
-    /* compact mode (default) emits tree tables; format:"json" emits the
-     * same model as structured JSON ({cols, rows}; full adds a per-row
-     * source cell; files is a plain list). */
+    /* Compact mode defaults to the lean tree. format:"json" preserves the
+     * released machine shape ({cols, rows}; full adds a per-row source cell;
+     * files is a plain list). */
     char *sc_format = cbm_mcp_get_string_arg(args, "format");
     bool sc_legacy_json = sc_format && strcmp(sc_format, "json") == 0;
     free(sc_format);
 
-    char *result = NULL;
-    if (mode == 0 && !sc_legacy_json) {
-        char *toon_text =
-            assemble_search_output_toon(sr, sr_count, raw, raw_count, gm_count, limit,
-                                        pat_has_pipe && !use_regex, cbm_now_ms() - search_t0);
-        result = cbm_mcp_text_result(toon_text ? toon_text : "out of memory", toon_text == NULL);
-        free(toon_text);
-    } else {
-        result = assemble_search_output(sr, sr_count, raw, raw_count, gm_count, limit, mode,
-                                        context_lines, root_path, pat_has_pipe && !use_regex,
-                                        cbm_now_ms() - search_t0);
+    int result_start = result_offset < sr_count ? result_offset : sr_count;
+    int output_count = sr_count - result_start;
+    if (output_count > result_limit) {
+        output_count = result_limit;
+    }
+    int raw_start = raw_offset < raw_count ? raw_offset : raw_count;
+    int raw_output = raw_stored_count;
+    search_dir_count_t *directories = NULL;
+    int dir_total = 0;
+    if (!aggregate_search_dirs(sr, sr_count, &directories, &dir_total)) {
+        free_search_results(sr, sr_count);
+        free_grep_matches(raw, raw_stored_count);
+        free(root_path);
+        free(pattern);
+        free(project);
+        free(file_pattern);
+        if (has_path_filter) {
+            cbm_regfree(&path_regex);
+        }
+        return cbm_mcp_text_result("out of memory", true);
+    }
+    free_search_dirs(directories, dir_total);
+    int directory_start = directory_offset < dir_total ? directory_offset : dir_total;
+    int directory_output = dir_total - directory_start;
+    if (directory_output > directory_limit) {
+        directory_output = directory_limit;
+    }
+    uint64_t elapsed_ms = cbm_now_ms() - search_t0;
+    bool warn_literal_pipe = pat_has_pipe && !use_regex;
+    char *payload = render_search_payload(
+        sr, sr_count, raw, raw_count, raw_content_truncated, gm_count, result_start, result_limit,
+        output_count, raw_start, raw_output, directory_start, directory_output, raw_limit,
+        directory_limit, match_limit, mode, context_lines, source_max_lines, root_path,
+        scan_saturated, warn_literal_pipe, elapsed_ms, false, sc_legacy_json);
+
+    if (payload && strlen(payload) > byte_budget) {
+        free(payload);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, raw_content_truncated, gm_count, result_start,
+            result_limit, output_count, raw_start, raw_output, directory_start, directory_output,
+            raw_limit, directory_limit, match_limit, mode, context_lines, source_max_lines,
+            root_path, scan_saturated, warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+    }
+
+    /* Preserve ranked graph answers. Unclassified raw grep rows and directory
+     * diagnostics yield first, at whole-row boundaries. */
+    while (payload && strlen(payload) > byte_budget && raw_output > 0) {
+        raw_output--;
+        free(payload);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, raw_content_truncated, gm_count, result_start,
+            result_limit, output_count, raw_start, raw_output, directory_start, directory_output,
+            raw_limit, directory_limit, match_limit, mode, context_lines, source_max_lines,
+            root_path, scan_saturated, warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+    }
+    while (payload && strlen(payload) > byte_budget && directory_output > 0) {
+        directory_output--;
+        free(payload);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, raw_content_truncated, gm_count, result_start,
+            result_limit, output_count, raw_start, raw_output, directory_start, directory_output,
+            raw_limit, directory_limit, match_limit, mode, context_lines, source_max_lines,
+            root_path, scan_saturated, warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+    }
+
+    /* Full source is the next detail tier. Find the largest whole-line window
+     * that fits while retaining every ranked result identity. */
+    if (payload && strlen(payload) > byte_budget && mode == 1 && source_max_lines > 0) {
+        int low = 0;
+        int high = source_max_lines - 1;
+        int best_lines = -1;
+        char *best_payload = NULL;
+        while (low <= high) {
+            int middle = low + (high - low) / 2;
+            char *candidate = render_search_payload(
+                sr, sr_count, raw, raw_count, raw_content_truncated, gm_count, result_start,
+                result_limit, output_count, raw_start, raw_output, directory_start,
+                directory_output, raw_limit, directory_limit, match_limit, mode, context_lines,
+                middle, root_path, scan_saturated, warn_literal_pipe, elapsed_ms, true,
+                sc_legacy_json);
+            if (candidate && strlen(candidate) <= byte_budget) {
+                free(best_payload);
+                best_payload = candidate;
+                best_lines = middle;
+                low = middle + 1;
+            } else {
+                free(candidate);
+                high = middle - 1;
+            }
+        }
+        free(payload);
+        if (best_payload) {
+            payload = best_payload;
+            source_max_lines = best_lines;
+        } else {
+            source_max_lines = 0;
+            payload = render_search_payload(
+                sr, sr_count, raw, raw_count, raw_content_truncated, gm_count, result_start,
+                result_limit, output_count, raw_start, raw_output, directory_start,
+                directory_output, raw_limit, directory_limit, match_limit, mode, context_lines,
+                source_max_lines, root_path, scan_saturated, warn_literal_pipe, elapsed_ms, true,
+                sc_legacy_json);
+        }
+    }
+
+    /* If identities themselves exceed the ceiling, find the largest fitting
+     * row prefix. Check every smaller prefix in descending order: response-local
+     * prefix factoring can activate at a threshold, so encoded size is not
+     * guaranteed to be monotonic in the row count. */
+    if (payload && strlen(payload) > byte_budget && output_count > 0) {
+        char *best_payload = NULL;
+        for (int candidate_rows = output_count - 1; candidate_rows >= 0; candidate_rows--) {
+            char *candidate = render_search_payload(
+                sr, sr_count, raw, raw_count, raw_content_truncated, gm_count, result_start,
+                result_limit, candidate_rows, raw_start, raw_output, directory_start,
+                directory_output, raw_limit, directory_limit, match_limit, mode, context_lines,
+                source_max_lines, root_path, scan_saturated, warn_literal_pipe, elapsed_ms, true,
+                sc_legacy_json);
+            if (candidate && strlen(candidate) <= byte_budget) {
+                best_payload = candidate;
+                break;
+            }
+            free(candidate);
+        }
+        free(payload);
+        payload = best_payload;
+    }
+
+    if (!payload || strlen(payload) > byte_budget) {
+        free(payload);
+        payload = search_budget_floor(sr_count, raw_count, gm_count, result_start, result_limit,
+                                      raw_start, raw_limit, directory_start, directory_limit,
+                                      dir_total, scan_saturated, sc_legacy_json, max_output_tokens);
     }
-    free(gm);
-    free(sr);
-    free(raw);
+    char *result = cbm_mcp_text_result(payload ? payload : "out of memory", payload == NULL);
+    free(payload);
+    free_search_results(sr, sr_count);
+    free_grep_matches(raw, raw_stored_count);
     free(root_path);
     free(pattern);
     free(project);
@@ -10112,23 +13644,17 @@ static void detect_collect_seeds(cbm_store_t *store, const char *project, const
  * ("src/mcp/mcp.c" -> "src/mcp"), a quotient of the blast radius coarse enough
  * to fit yet specific enough to localize (one segment collapses a whole tree
  * to "src"). Falls back to one segment, then the whole path. */
-static void detect_module_of(const char *file, char *out, size_t outsz) {
+static char *detect_module_of(const char *file) {
     if (!file || !file[0]) {
-        snprintf(out, outsz, "(root)");
-        return;
+        return heap_strdup("(root)");
     }
     const char *s1 = strchr(file, '/');
     if (!s1) {
-        snprintf(out, outsz, "%s", file);
-        return;
+        return heap_strdup(file);
     }
     const char *s2 = strchr(s1 + 1, '/');
     size_t len = s2 ? (size_t)(s2 - file) : strlen(file);
-    if (len >= outsz) {
-        len = outsz - 1;
-    }
-    memcpy(out, file, len);
-    out[len] = '\0';
+    return cbm_strndup(file, len);
 }
 
 /* Aggregate the impact set into the 2-segment module rollup. Fills up to
@@ -10137,80 +13663,417 @@ static void detect_module_of(const char *file, char *out, size_t outsz) {
  * tree and json emitters so both encodings carry the same model. */
 enum { DETECT_MODCAP = 256 };
 
-static int detect_module_rollup(const cbm_traverse_result_t *impact, char mods[][CBM_SZ_128],
-                                int *mcnt, int *overflow) {
+typedef struct {
+    char *name;
+    int count;
+} detect_module_row_t;
+
+static int detect_module_rollup(const cbm_traverse_result_t *impact, detect_module_row_t *modules,
+                                int *overflow) {
     int nmods = 0;
     *overflow = 0;
     for (int i = 0; i < impact->visited_count; i++) {
-        char m[CBM_SZ_128];
-        detect_module_of(impact->visited[i].node.file_path, m, sizeof(m));
+        char *module = detect_module_of(impact->visited[i].node.file_path);
+        if (!module) {
+            (*overflow)++;
+            continue;
+        }
         int j = 0;
         for (; j < nmods; j++) {
-            if (strcmp(mods[j], m) == 0) {
-                mcnt[j]++;
+            if (strcmp(modules[j].name, module) == 0) {
+                modules[j].count++;
                 break;
             }
         }
         if (j == nmods) {
             if (nmods < DETECT_MODCAP) {
-                snprintf(mods[nmods], CBM_SZ_128, "%s", m);
-                mcnt[nmods] = 1;
+                modules[nmods].name = module;
+                modules[nmods].count = 1;
                 nmods++;
+                module = NULL;
             } else {
                 (*overflow)++;
             }
         }
+        free(module);
     }
     return nmods;
 }
 
-/* Emit the impacted set as a grouped tree leg: rows grouped under their shared
- * (qn-prefix, file), `name label hop` per row. At most `limit` rows are listed
- * (the visited array is hop-ordered, so the closest — highest-signal — impact
- * shows first); impacted_total always carries the exact full count, and
- * `impacted_shown < impacted_total` is the honest truncation signal. The
- * module rollup (emitted by the caller) stays complete regardless. */
-static void detect_emit_impacted_tree(cbm_sb_t *sb, cbm_traverse_result_t *tr, int limit) {
+static void detect_module_rollup_free(detect_module_row_t *modules, int count) {
+    for (int i = 0; i < count; i++) {
+        free(modules[i].name);
+    }
+    free(modules);
+}
+
+/* Emit one losslessly pageable window of the impacted set. The visited array
+ * is hop-ordered, so page zero preserves the closest, highest-signal rows.
+ * Engine saturation is reported as a lower-bound total, never as an exact
+ * count. */
+static void detect_emit_impacted_tree(cbm_sb_t *sb, const cbm_traverse_result_t *tr, int start,
+                                      int count, bool engine_saturated) {
     cbm_tree_scalar_int(sb, "impacted_total", tr->visited_count);
-    int shown = tr->visited_count < limit ? tr->visited_count : limit;
+    cbm_tree_scalar_str(sb, "impacted_total_relation", engine_saturated ? "gte" : "eq");
+    int shown = count;
     /* qn order for stable grouping, but keep hop-closeness: sort by (hop) is
      * lost under qn sort, so group AFTER selecting the nearest `shown` rows —
      * the visited array is already (hop,id)-ordered from the BFS. */
-    char hdr[CBM_SZ_128];
-    snprintf(hdr, sizeof(hdr),
-             "impacted_shown: %d\nimpacted: %d  (rows: name label hop; qn = group prefix + \".\" "
-             "+ name; nearest hops first)\n",
-             shown, shown);
-    cbm_sb_append(sb, hdr);
-    if (shown > 1) {
-        qsort(tr->visited, (size_t)shown, sizeof(cbm_node_hop_t), tree_hop_cmp_qn);
-    }
-    char cur_group[CBM_SZ_1K] = "";
-    for (int i = 0; i < shown; i++) {
-        const char *qn =
-            tr->visited[i].node.qualified_name ? tr->visited[i].node.qualified_name : "";
-        const char *file = tr->visited[i].node.file_path ? tr->visited[i].node.file_path : "";
-        size_t plen = sg_qn_prefix_len(qn);
-        char group[CBM_SZ_1K];
-        snprintf(group, sizeof(group), "%.*s (%s)", (int)plen, qn, file);
-        if (strcmp(group, cur_group) != 0) {
-            snprintf(cur_group, sizeof(cur_group), "%s", group);
-            cbm_sb_append(sb, group);
-            cbm_sb_append(sb, ":\n");
+    cbm_tree_scalar_int(sb, "impacted_shown", shown);
+    cbm_node_hop_t *selected = NULL;
+    const cbm_node_hop_t *rows = tr->visited;
+    if (shown > 0) {
+        selected = malloc((size_t)shown * sizeof(*selected));
+        if (selected) {
+            memcpy(selected, tr->visited + start, (size_t)shown * sizeof(*selected));
+            rows = selected;
+        } else {
+            rows = tr->visited + start;
+        }
+    }
+    if (shown > 1 && selected) {
+        qsort(selected, (size_t)shown, sizeof(*selected), tree_hop_cmp_qn);
+    }
+    static const char *const columns[] = {"qn", "label", "file", "hop"};
+    const char **cells = shown > 0 ? calloc((size_t)shown * 4U, sizeof(*cells)) : NULL;
+    char (*hop_text)[32] = shown > 0 ? calloc((size_t)shown, sizeof(*hop_text)) : NULL;
+    if (shown == 0 || (cells && hop_text)) {
+        for (int i = 0; i < shown; i++) {
+            size_t base = (size_t)i * 4U;
+            cells[base] = rows[i].node.qualified_name ? rows[i].node.qualified_name : "";
+            cells[base + 1U] = rows[i].node.label ? rows[i].node.label : "";
+            cells[base + 2U] = rows[i].node.file_path ? rows[i].node.file_path : "";
+            snprintf(hop_text[i], sizeof(hop_text[i]), "%d", rows[i].hop);
+            cells[base + 3U] = hop_text[i];
+        }
+        static const bool string_cols[] = {true, true, true, false};
+        static const bool prefix_cols[] = {true, false, true, false};
+        cbm_tree_table_rows_profiled(sb, "impacted", shown, columns, 4, cells, string_cols,
+                                     prefix_cols);
+    } else {
+        cbm_tree_table_header(sb, "impacted", 0, columns, 4);
+        cbm_tree_scalar_str(sb, "impacted_render_error", "out_of_memory");
+    }
+    free(hop_text);
+    free(cells);
+    free(selected);
+    bool has_more = start + shown < tr->visited_count;
+    cbm_tree_scalar_bool(sb, "impacted_has_more", has_more);
+    if (has_more && shown > 0) {
+        cbm_tree_scalar_int(sb, "impacted_next_offset", start + shown);
+    } else if (has_more) {
+        cbm_tree_scalar_bool(sb, "impacted_continuation_requires_higher_budget", true);
+    }
+}
+
+/* Portable, allocation-backed record reader. Git's -z formats preserve UTF-8
+ * and allow every path byte except NUL, including newlines. A fixed or
+ * line-based buffer would either quote or split valid paths. */
+static char *detect_read_record(FILE *stream, int delimiter, bool *oom, bool *terminated) {
+    cbm_sb_t record;
+    cbm_sb_init(&record);
+    bool saw_input = false;
+    if (terminated) {
+        *terminated = false;
+    }
+    for (;;) {
+        int ch = fgetc(stream);
+        if (ch == EOF) {
+            break;
+        }
+        saw_input = true;
+        if (ch == delimiter) {
+            if (terminated) {
+                *terminated = true;
+            }
+            break;
+        }
+        char byte = (char)ch;
+        cbm_sb_append_n(&record, &byte, 1);
+        if (record.oom) {
+            break;
+        }
+    }
+    if (record.oom) {
+        if (oom) {
+            *oom = true;
+        }
+        cbm_sb_free(&record);
+        return NULL;
+    }
+    if (!saw_input) {
+        cbm_sb_free(&record);
+        return NULL;
+    }
+    return cbm_sb_finish(&record);
+}
+
+static bool detect_add_changed_path(char ***files, int *file_count, int *file_cap,
+                                    const char *path) {
+    if (!path || !path[0]) {
+        return true;
+    }
+    for (int i = 0; i < *file_count; i++) {
+        if (strcmp((*files)[i], path) == 0) {
+            return true;
+        }
+    }
+    if (*file_count >= *file_cap) {
+        int next_cap = *file_cap ? *file_cap * 2 : 16;
+        char **grown = realloc(*files, (size_t)next_cap * sizeof(*grown));
+        if (!grown) {
+            return false;
+        }
+        *files = grown;
+        *file_cap = next_cap;
+    }
+    char *copy = heap_strdup(path);
+    if (!copy) {
+        return false;
+    }
+    (*files)[(*file_count)++] = copy;
+    return true;
+}
+
+static int detect_changed_path_compare(const void *left, const void *right) {
+    const char *const *left_path = left;
+    const char *const *right_path = right;
+    return strcmp(*left_path, *right_path);
+}
+
+static bool detect_valid_object_id(const char *value) {
+    size_t length = value ? strlen(value) : 0;
+    if (length != 40 && length != 64) {
+        return false;
+    }
+    for (size_t i = 0; i < length; i++) {
+        if (!isxdigit((unsigned char)value[i])) {
+            return false;
+        }
+    }
+    return true;
+}
+
+typedef struct {
+    char stream;       /* c=changed files, i=impacted symbols, m=module rollup */
+    char snapshot[33]; /* first 128 bits of the SHA-256 live-state fingerprint */
+    uint64_t qhash;    /* semantic query identity; page sizing is deliberately excluded */
+    int offset;        /* next row in this independently pageable stream */
+} detect_cursor_t;
+
+static uint64_t detect_params_hash(const char *project, const char *base_branch, const char *scope,
+                                   const char *direction, int depth) {
+    uint64_t hash = 0xcbf29ce484222325ULL;
+    hash = cursor_fnv1a64(project ? project : "", hash);
+    hash = cursor_fnv1a64("|", hash);
+    hash = cursor_fnv1a64(base_branch ? base_branch : "", hash);
+    hash = cursor_fnv1a64("|", hash);
+    hash = cursor_fnv1a64(scope ? scope : "impact", hash);
+    hash = cursor_fnv1a64("|", hash);
+    hash = cursor_fnv1a64(direction ? direction : "inbound", hash);
+    char depth_text[32];
+    snprintf(depth_text, sizeof(depth_text), "|%d", depth);
+    return cursor_fnv1a64(depth_text, hash);
+}
+
+static void detect_cursor_encode(char stream, const char snapshot[33], uint64_t qhash, int offset,
+                                 char out[80]) {
+    snprintf(out, 80, "d1.%c.%s.%016llx.%d", stream, snapshot, (unsigned long long)qhash, offset);
+}
+
+static const char *detect_cursor_decode(const char *token, char expected_stream,
+                                        const char current_snapshot[33], uint64_t expected_qhash,
+                                        detect_cursor_t *out) {
+    memset(out, 0, sizeof(*out));
+    if (!token || strncmp(token, "d1.", 3) != 0 || token[3] != expected_stream || token[4] != '.') {
+        return "invalid_cursor: unrecognized detect_changes cursor — rerun without the cursor";
+    }
+    out->stream = token[3];
+    const char *snapshot_start = token + 5;
+    const char *snapshot_end = strchr(snapshot_start, '.');
+    if (!snapshot_end || snapshot_end - snapshot_start != 32) {
+        return "invalid_cursor: unrecognized detect_changes cursor — rerun without the cursor";
+    }
+    for (const char *digit = snapshot_start; digit < snapshot_end; digit++) {
+        if (!isxdigit((unsigned char)*digit)) {
+            return "invalid_cursor: unrecognized detect_changes cursor — rerun without the cursor";
+        }
+    }
+    memcpy(out->snapshot, snapshot_start, 32);
+    out->snapshot[32] = '\0';
+
+    const char *hash_start = snapshot_end + 1;
+    const char *hash_end = strchr(hash_start, '.');
+    if (!hash_end || hash_end - hash_start != 16) {
+        return "invalid_cursor: unrecognized detect_changes cursor — rerun without the cursor";
+    }
+    for (const char *digit = hash_start; digit < hash_end; digit++) {
+        if (!isxdigit((unsigned char)*digit)) {
+            return "invalid_cursor: unrecognized detect_changes cursor — rerun without the cursor";
+        }
+    }
+    errno = 0;
+    char *parsed_end = NULL;
+    unsigned long long parsed_hash = strtoull(hash_start, &parsed_end, 16);
+    if (errno == ERANGE || parsed_end != hash_end) {
+        return "invalid_cursor: unrecognized detect_changes cursor — rerun without the cursor";
+    }
+    errno = 0;
+    long parsed_offset = strtol(hash_end + 1, &parsed_end, 10);
+    if (errno == ERANGE || parsed_end == hash_end + 1 || *parsed_end != '\0' || parsed_offset < 1 ||
+        parsed_offset > INT_MAX) {
+        return "invalid_cursor: unrecognized detect_changes cursor — rerun without the cursor";
+    }
+    out->qhash = (uint64_t)parsed_hash;
+    out->offset = (int)parsed_offset;
+    if (out->qhash != expected_qhash) {
+        return "cursor_params_mismatch: detect_changes cursor belongs to different semantic "
+               "arguments — rerun without the cursor";
+    }
+    if (strcmp(out->snapshot, current_snapshot) != 0) {
+        return "snapshot_changed: commits, worktree, or graph changed since this cursor was issued "
+               "— rerun detect_changes without the cursor";
+    }
+    return NULL;
+}
+
+static void detect_snapshot_add_field(cbm_sha256_ctx *hash, const char *value) {
+    size_t length = value ? strlen(value) : 0;
+    char length_text[32];
+    int count = snprintf(length_text, sizeof(length_text), "%zu:", length);
+    cbm_sha256_update(hash, length_text, (size_t)count);
+    if (length > 0) {
+        cbm_sha256_update(hash, value, length);
+    }
+    cbm_sha256_update(hash, "|", 1);
+}
+
+static bool detect_snapshot_add_changed_file(cbm_mcp_server_t *srv, cbm_sha256_ctx *hash,
+                                             const char *root_path, const char *relative_path) {
+    detect_snapshot_add_field(hash, relative_path);
+    size_t root_len = strlen(root_path);
+    size_t relative_len = strlen(relative_path);
+    if (root_len > (size_t)-1 - relative_len - 2U) {
+        detect_snapshot_add_field(hash, "path_overflow");
+        return false;
+    }
+    char *absolute = malloc(root_len + relative_len + 2U);
+    if (!absolute) {
+        detect_snapshot_add_field(hash, "path_oom");
+        return false;
+    }
+    memcpy(absolute, root_path, root_len);
+    absolute[root_len] = '/';
+    memcpy(absolute + root_len + 1U, relative_path, relative_len + 1U);
+
+    cbm_path_info_t info = {0};
+    int info_status = cbm_path_info_utf8(absolute, &info);
+    if (info_status == CBM_PATH_INFO_ABSENT) {
+        detect_snapshot_add_field(hash, "absent");
+        free(absolute);
+        return true;
+    }
+    if (info_status != CBM_PATH_INFO_OK) {
+        /* Hash the observed failure state for diagnostics, but do not issue a
+         * cursor from incomplete evidence. Offset paging remains available. */
+        detect_snapshot_add_field(hash, "metadata_unavailable");
+        free(absolute);
+        return false;
+    }
+    char metadata[160];
+    snprintf(metadata, sizeof(metadata), "r%d:d%d:l%d:s%lld:m%lld", info.is_regular ? 1 : 0,
+             info.is_directory ? 1 : 0, info.is_symlink ? 1 : 0, (long long)info.size,
+             (long long)info.mtime_ns);
+    detect_snapshot_add_field(hash, metadata);
+    bool complete = true;
+    if (info.is_regular) {
+        FILE *file = NULL;
+#ifdef CBM_ENABLE_TEST_SEAMS
+        bool allow_open = !srv || !srv->snapshot_read_test_hook ||
+                          srv->snapshot_read_test_hook(srv->snapshot_read_test_context, absolute);
+        if (allow_open) {
+            file = cbm_fopen(absolute, "rb");
+        }
+#else
+        (void)srv;
+        file = cbm_fopen(absolute, "rb");
+#endif
+        if (file) {
+            unsigned char buffer[64 * 1024];
+            size_t count;
+            while ((count = fread(buffer, 1, sizeof(buffer), file)) > 0) {
+                cbm_sha256_update(hash, buffer, count);
+            }
+            bool read_error = ferror(file) != 0;
+            detect_snapshot_add_field(hash, read_error ? "read_error" : "read_complete");
+            complete = !read_error;
+            (void)fclose(file);
+        } else {
+            detect_snapshot_add_field(hash, "open_error");
+            complete = false;
+        }
+    } else if (info.is_symlink) {
+        /* lstat-style metadata identifies the link object but not its target
+         * bytes. The cross-platform metadata API intentionally does not expose
+         * a readlink/reparse payload, so fail closed instead of pretending the
+         * cursor is bound to the changed link identity. */
+        detect_snapshot_add_field(hash, "link_identity_unavailable");
+        complete = false;
+    }
+    free(absolute);
+    return complete;
+}
+
+static bool detect_snapshot_fingerprint(cbm_mcp_server_t *srv, const char *root_path,
+                                        const char *head_oid, const char *base_oid,
+                                        const char *merge_base, const char *generation,
+                                        char **files, int file_count,
+                                        const cbm_traverse_result_t *impact,
+                                        const detect_module_row_t *modules, int module_count,
+                                        int module_overflow, char out[33]) {
+    cbm_sha256_ctx hash;
+    cbm_sha256_init(&hash);
+    detect_snapshot_add_field(&hash, "detect_changes_snapshot_v1");
+    detect_snapshot_add_field(&hash, head_oid);
+    detect_snapshot_add_field(&hash, base_oid);
+    detect_snapshot_add_field(&hash, merge_base);
+    detect_snapshot_add_field(&hash, generation);
+    bool complete = true;
+    for (int i = 0; i < file_count; i++) {
+        if (!detect_snapshot_add_changed_file(srv, &hash, root_path, files[i])) {
+            complete = false;
+        }
+    }
+    if (impact) {
+        for (int i = 0; i < impact->visited_count; i++) {
+            detect_snapshot_add_field(&hash, impact->visited[i].node.qualified_name);
+            detect_snapshot_add_field(&hash, impact->visited[i].node.label);
+            detect_snapshot_add_field(&hash, impact->visited[i].node.file_path);
+            char row_metadata[64];
+            snprintf(row_metadata, sizeof(row_metadata), "%d:%lld", impact->visited[i].hop,
+                     (long long)impact->visited[i].node.id);
+            detect_snapshot_add_field(&hash, row_metadata);
         }
-        char row[CBM_SZ_512];
-        snprintf(row, sizeof(row), "  %s %s %d\n", plen ? qn + plen + 1 : qn,
-                 tr->visited[i].node.label ? tr->visited[i].node.label : "", tr->visited[i].hop);
-        cbm_sb_append(sb, row);
     }
-    if (shown < tr->visited_count) {
-        char more[CBM_SZ_256];
-        snprintf(more, sizeof(more),
-                 "impacted_omitted: %d  (see impacted_modules for the full rollup; raise 'limit' "
-                 "or lower 'depth' to see specifics)\n",
-                 tr->visited_count - shown);
-        cbm_sb_append(sb, more);
+    for (int i = 0; i < module_count; i++) {
+        detect_snapshot_add_field(&hash, modules[i].name);
+        char count_text[32];
+        snprintf(count_text, sizeof(count_text), "%d", modules[i].count);
+        detect_snapshot_add_field(&hash, count_text);
+    }
+    char overflow_text[32];
+    snprintf(overflow_text, sizeof(overflow_text), "%d", module_overflow);
+    detect_snapshot_add_field(&hash, overflow_text);
+
+    uint8_t digest[CBM_SHA256_DIGEST_LEN];
+    static const char hex[] = "0123456789abcdef";
+    cbm_sha256_final(&hash, digest);
+    for (int i = 0; i < 16; i++) {
+        out[i * 2] = hex[digest[i] >> 4];
+        out[i * 2 + 1] = hex[digest[i] & 0x0f];
     }
+    out[32] = '\0';
+    return complete;
 }
 
 static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
@@ -10221,7 +14084,8 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     int depth = cbm_mcp_get_int_arg(args, "depth", MCP_DEFAULT_BFS_DEPTH);
     depth = clamp_mcp_depth(depth, "detect_changes");
 
-    /* scope: "files" = just changed files, "symbols" = files + symbols (default) */
+    /* scope: "files" = changed files only; "impact" = files + symbols (default).
+     * Keep accepting the legacy "symbols" spelling for compatibility. */
     bool want_symbols = !scope || strcmp(scope, "symbols") == 0 || strcmp(scope, "impact") == 0;
 
     /* `since` (e.g. "HEAD~10", "v0.5.0") is the documented diff base but was
@@ -10273,69 +14137,22 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         return cbm_mcp_text_result("project path contains invalid characters", true);
     }
 
-    /* Get changed files via git (-C avoids cd + quoting issues on Windows).
-     * Three sources are merged:
-     *   1. committed changes vs base   (diff <base>...HEAD)
-     *   2. unstaged tracked changes    (diff)
-     *   3. untracked + staged-new files (status --porcelain) — these are
-     *      invisible to `git diff` and were silently missed before, so a
-     *      brand-new file never appeared until a manual re-index (#520).
-     * status --porcelain prefixes each path with a 2-char code + space
-     * ("?? path", "A  path"); the prefix is stripped when parsing below. */
-    char cmd[CBM_SZ_2K];
-#ifdef _WIN32
-    snprintf(cmd, sizeof(cmd),
-             "git -C \"%s\" diff --name-only \"%s\"...HEAD 2>NUL & "
-             "git -C \"%s\" diff --name-only 2>NUL & "
-             "git --no-optional-locks -C \"%s\" status --porcelain "
-             "--untracked-files=normal 2>NUL",
-             root_path, base_branch, root_path, root_path);
-#else
-    snprintf(cmd, sizeof(cmd),
-             "{ git -C '%s' diff --name-only '%s'...HEAD 2>/dev/null; "
-             "git -C '%s' diff --name-only 2>/dev/null; "
-             "git --no-optional-locks -C '%s' status --porcelain "
-             "--untracked-files=normal 2>/dev/null; } | sort -u",
-             root_path, base_branch, root_path, root_path);
-#endif
-
-    char output_path[CBM_SZ_2K] = {0};
-    cbm_proc_result_t git_result = {0};
-    int git_run = mcp_run_shell_command_cancellable(srv, cmd, output_path, &git_result);
-    bool git_cancelled = git_result.cancellation_requested || mcp_request_cancelled(srv);
-    if (git_cancelled) {
-        (void)cbm_unlink(output_path);
-        free(root_path);
-        free(project);
-        free(base_branch);
-        free(scope);
-        return cbm_mcp_text_result("detect_changes cancelled for this request", true);
-    }
-    if (git_run != 0) {
-        (void)cbm_unlink(output_path);
-        char errmsg[CBM_SZ_256];
-        snprintf(errmsg, sizeof(errmsg),
-                 "git diff failed: the contained command could not complete. "
-                 "Check that git is installed.");
-        free(root_path);
-        free(project);
-        free(base_branch);
-        free(scope);
-        return cbm_mcp_text_result(errmsg, true);
-    }
-    FILE *fp = cbm_fopen(output_path, "rb");
-    if (!fp) {
-        (void)cbm_unlink(output_path);
+    /* Every detect snapshot and cursor is generation-bound. Validate the
+     * metadata immediately after store resolution so fresh requests and
+     * cursor replays fail identically before Git work or cursor minting. */
+    cbm_store_t *store = srv->store;
+    char generation[96] = "";
+    if (cbm_store_generation(store, generation, sizeof(generation)) != CBM_STORE_OK) {
         free(root_path);
         free(project);
         free(base_branch);
         free(scope);
-        return cbm_mcp_text_result("git diff failed: contained output could not be read", true);
+        return cbm_mcp_text_result(
+            "index_metadata_error: generation metadata is unreadable; reindex before detecting "
+            "changes",
+            true);
     }
 
-    /* resolve_store already called via get_project_root above */
-    cbm_store_t *store = srv->store;
-
     /* Direction of impact. Default inbound = the BLAST RADIUS: the transitive
      * CALLERS of the changed symbols, which may need review. outbound = what
      * the changed code depends on; both = union. */
@@ -10357,16 +14174,311 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         free(project);
         free(base_branch);
         free(scope);
-        (void)fclose(fp);
-        (void)cbm_unlink(output_path);
         return cbm_mcp_text_result(errbuf, true);
     }
     char *fmt = cbm_mcp_get_string_arg(args, "format");
     bool legacy_json = fmt && strcmp(fmt, "json") == 0;
     free(fmt);
 
-    /* Per-symbol impacted-row display cap (the module rollup stays complete).
-     * impacted_total always reports the true count, so this never hides scale. */
+    /* Freeze both endpoints before collecting paths. A failed or unknown base
+     * is a request error, never an exact-looking empty diff, and a concurrent
+     * HEAD advance cannot mix revisions within one answer. */
+    char head_oid[65] = "";
+    char base_oid[65] = "";
+    char resolve_cmd[CBM_SZ_2K];
+#ifdef _WIN32
+    snprintf(resolve_cmd, sizeof(resolve_cmd),
+             "git -C \"%s\" rev-parse \"HEAD^{commit}\" \"%s^{commit}\" 2>NUL", root_path,
+             base_branch);
+#else
+    snprintf(resolve_cmd, sizeof(resolve_cmd),
+             "git -C '%s' rev-parse 'HEAD^{commit}' '%s^{commit}' 2>/dev/null", root_path,
+             base_branch);
+#endif
+    char resolve_output_path[CBM_SZ_2K] = {0};
+    cbm_proc_result_t resolve_result = {0};
+    int resolve_run =
+        mcp_run_shell_command_cancellable(srv, resolve_cmd, resolve_output_path, &resolve_result);
+    bool resolve_cancelled = resolve_result.cancellation_requested || mcp_request_cancelled(srv);
+    bool resolve_oom = false;
+    char *resolved_head = NULL;
+    char *resolved_base = NULL;
+    FILE *resolve_fp = resolve_run == 0 && resolve_result.exit_code == 0 && !resolve_cancelled
+                           ? cbm_fopen(resolve_output_path, "rb")
+                           : NULL;
+    if (resolve_fp) {
+        bool head_terminated = false;
+        bool base_terminated = false;
+        resolved_head = detect_read_record(resolve_fp, '\n', &resolve_oom, &head_terminated);
+        resolved_base = detect_read_record(resolve_fp, '\n', &resolve_oom, &base_terminated);
+        if (resolved_head) {
+            size_t length = strlen(resolved_head);
+            if (length > 0 && resolved_head[length - 1] == '\r') {
+                resolved_head[--length] = '\0';
+            }
+            if (head_terminated && detect_valid_object_id(resolved_head)) {
+                memcpy(head_oid, resolved_head, length + 1U);
+            }
+        }
+        if (resolved_base) {
+            size_t length = strlen(resolved_base);
+            if (length > 0 && resolved_base[length - 1] == '\r') {
+                resolved_base[--length] = '\0';
+            }
+            if (base_terminated && detect_valid_object_id(resolved_base)) {
+                memcpy(base_oid, resolved_base, length + 1U);
+            }
+        }
+        (void)fclose(resolve_fp);
+    }
+    free(resolved_head);
+    free(resolved_base);
+    if (resolve_output_path[0]) {
+        (void)cbm_unlink(resolve_output_path);
+    }
+    if (resolve_cancelled || resolve_run != 0 || resolve_result.exit_code != 0 || resolve_oom ||
+        !head_oid[0] || !base_oid[0]) {
+        free(direction);
+        free(root_path);
+        free(project);
+        free(base_branch);
+        free(scope);
+        if (resolve_cancelled) {
+            return cbm_mcp_text_result("detect_changes cancelled for this request", true);
+        }
+        if (resolve_run != 0) {
+            return cbm_mcp_text_result(
+                "git revision resolution failed: the contained command could not complete", true);
+        }
+        return cbm_mcp_text_result(
+            "git revision resolution failed: base_branch or HEAD is not a commit", true);
+    }
+
+    char merge_base[65] = "";
+    char mbcmd[CBM_SZ_2K];
+#ifdef _WIN32
+    snprintf(mbcmd, sizeof(mbcmd), "git -C \"%s\" merge-base \"%s\" \"%s\" 2>NUL", root_path,
+             base_oid, head_oid);
+#else
+    snprintf(mbcmd, sizeof(mbcmd), "git -C '%s' merge-base '%s' '%s' 2>/dev/null", root_path,
+             base_oid, head_oid);
+#endif
+    char mb_output_path[CBM_SZ_2K] = {0};
+    cbm_proc_result_t mb_result = {0};
+    int mb_run = mcp_run_shell_command_cancellable(srv, mbcmd, mb_output_path, &mb_result);
+    bool mb_cancelled = mb_result.cancellation_requested || mcp_request_cancelled(srv);
+    bool mb_oom = false;
+    bool mb_terminated = false;
+    char *mb_record = NULL;
+    FILE *mbfp = mb_run == 0 && mb_result.exit_code == 0 && !mb_cancelled
+                     ? cbm_fopen(mb_output_path, "rb")
+                     : NULL;
+    if (mbfp) {
+        mb_record = detect_read_record(mbfp, '\n', &mb_oom, &mb_terminated);
+        (void)fclose(mbfp);
+    }
+    if (mb_record) {
+        size_t length = strlen(mb_record);
+        if (length > 0 && mb_record[length - 1] == '\r') {
+            mb_record[--length] = '\0';
+        }
+        if (detect_valid_object_id(mb_record)) {
+            memcpy(merge_base, mb_record, length + 1U);
+        }
+    }
+    free(mb_record);
+    if (mb_output_path[0]) {
+        (void)cbm_unlink(mb_output_path);
+    }
+    if (mb_cancelled || mb_run != 0 || mb_result.exit_code != 0 || mb_oom || !merge_base[0]) {
+        free(direction);
+        free(root_path);
+        free(project);
+        free(base_branch);
+        free(scope);
+        if (mb_cancelled) {
+            return cbm_mcp_text_result("detect_changes cancelled for this request", true);
+        }
+        if (mb_run != 0) {
+            return cbm_mcp_text_result(
+                "git merge-base failed: the contained command could not complete", true);
+        }
+        return cbm_mcp_text_result(
+            "git merge-base failed: base_branch has no common ancestor with HEAD", true);
+    }
+
+    /* Collect exact Git path records. `-z` disables C-style path quoting and
+     * keeps embedded newlines intact. Diff and porcelain status stay separate:
+     * diff emits bare paths, while status emits typed `XY destination` records
+     * and an extra source record for renames/copies. */
+    char **files = NULL;
+    int file_count = 0;
+    int file_cap = 0;
+    bool changed_path_oom = false;
+    bool changed_path_malformed = false;
+
+    char diff_cmd[CBM_SZ_2K];
+#ifdef _WIN32
+    snprintf(diff_cmd, sizeof(diff_cmd),
+             "git -c core.quotePath=false -C \"%s\" diff --name-only -z \"%s\" \"%s\" -- 2>NUL "
+             "&& git -c core.quotePath=false -C \"%s\" diff --name-only -z -- 2>NUL",
+             root_path, merge_base, head_oid, root_path);
+#else
+    snprintf(diff_cmd, sizeof(diff_cmd),
+             "git -c core.quotePath=false -C '%s' diff --name-only -z '%s' '%s' -- 2>/dev/null "
+             "&& git -c core.quotePath=false -C '%s' diff --name-only -z -- 2>/dev/null",
+             root_path, merge_base, head_oid, root_path);
+#endif
+    char diff_output_path[CBM_SZ_2K] = {0};
+    cbm_proc_result_t diff_result = {0};
+    int diff_run = mcp_run_shell_command_cancellable(srv, diff_cmd, diff_output_path, &diff_result);
+    bool diff_cancelled = diff_result.cancellation_requested || mcp_request_cancelled(srv);
+    FILE *diff_fp = diff_run == 0 && diff_result.exit_code == 0 && !diff_cancelled
+                        ? cbm_fopen(diff_output_path, "rb")
+                        : NULL;
+    bool diff_output_opened = diff_fp != NULL;
+    if (diff_fp) {
+        for (;;) {
+            bool terminated = false;
+            char *record = detect_read_record(diff_fp, '\0', &changed_path_oom, &terminated);
+            if (!record) {
+                break;
+            }
+            if (!terminated) {
+                changed_path_malformed = true;
+                free(record);
+                break;
+            }
+            if (!detect_add_changed_path(&files, &file_count, &file_cap, record)) {
+                changed_path_oom = true;
+                free(record);
+                break;
+            }
+            free(record);
+        }
+        (void)fclose(diff_fp);
+    }
+    if (diff_output_path[0]) {
+        (void)cbm_unlink(diff_output_path);
+    }
+    if (diff_cancelled || diff_run != 0 || diff_result.exit_code != 0 || !diff_output_opened ||
+        changed_path_oom || changed_path_malformed) {
+        for (int i = 0; i < file_count; i++) {
+            free(files[i]);
+        }
+        free(files);
+        free(direction);
+        free(root_path);
+        free(project);
+        free(base_branch);
+        free(scope);
+        if (diff_cancelled) {
+            return cbm_mcp_text_result("detect_changes cancelled for this request", true);
+        }
+        if (changed_path_oom) {
+            return cbm_mcp_text_result("out of memory while reading changed paths", true);
+        }
+        if (changed_path_malformed) {
+            return cbm_mcp_text_result("git diff returned a malformed path record", true);
+        }
+        return cbm_mcp_text_result(diff_run != 0
+                                       ? "git diff failed: the contained command could not complete"
+                                       : "git diff failed while collecting changed paths",
+                                   true);
+    }
+
+    char status_cmd[CBM_SZ_2K];
+#ifdef _WIN32
+    snprintf(status_cmd, sizeof(status_cmd),
+             "git --no-optional-locks -c core.quotePath=false -C \"%s\" status "
+             "--porcelain=v1 -z --untracked-files=all -- 2>NUL",
+             root_path);
+#else
+    snprintf(status_cmd, sizeof(status_cmd),
+             "git --no-optional-locks -c core.quotePath=false -C '%s' status "
+             "--porcelain=v1 -z --untracked-files=all -- 2>/dev/null",
+             root_path);
+#endif
+    char status_output_path[CBM_SZ_2K] = {0};
+    cbm_proc_result_t status_result = {0};
+    int status_run =
+        mcp_run_shell_command_cancellable(srv, status_cmd, status_output_path, &status_result);
+    bool status_cancelled = status_result.cancellation_requested || mcp_request_cancelled(srv);
+    FILE *status_fp = status_run == 0 && status_result.exit_code == 0 && !status_cancelled
+                          ? cbm_fopen(status_output_path, "rb")
+                          : NULL;
+    bool status_output_opened = status_fp != NULL;
+    if (status_fp) {
+        for (;;) {
+            bool terminated = false;
+            char *record = detect_read_record(status_fp, '\0', &changed_path_oom, &terminated);
+            if (!record) {
+                break;
+            }
+            size_t length = strlen(record);
+            bool typed = terminated && length > PAIR_LEN + 1U && record[PAIR_LEN] == ' ';
+            bool rename_or_copy = typed && (record[0] == 'R' || record[0] == 'C' ||
+                                            record[1] == 'R' || record[1] == 'C');
+            if (!typed) {
+                changed_path_malformed = true;
+                free(record);
+                break;
+            }
+            if (!detect_add_changed_path(&files, &file_count, &file_cap, record + PAIR_LEN + 1U)) {
+                changed_path_oom = true;
+                free(record);
+                break;
+            }
+            free(record);
+            if (rename_or_copy) {
+                bool source_terminated = false;
+                char *source =
+                    detect_read_record(status_fp, '\0', &changed_path_oom, &source_terminated);
+                if (!source || !source_terminated || !source[0]) {
+                    free(source);
+                    changed_path_malformed = !changed_path_oom;
+                    break;
+                }
+                free(source);
+            }
+        }
+        (void)fclose(status_fp);
+    }
+    if (status_output_path[0]) {
+        (void)cbm_unlink(status_output_path);
+    }
+    if (status_cancelled || status_run != 0 || status_result.exit_code != 0 ||
+        !status_output_opened || changed_path_oom || changed_path_malformed) {
+        for (int i = 0; i < file_count; i++) {
+            free(files[i]);
+        }
+        free(files);
+        free(direction);
+        free(root_path);
+        free(project);
+        free(base_branch);
+        free(scope);
+        if (status_cancelled) {
+            return cbm_mcp_text_result("detect_changes cancelled for this request", true);
+        }
+        if (changed_path_oom) {
+            return cbm_mcp_text_result("out of memory while reading changed paths", true);
+        }
+        if (changed_path_malformed) {
+            return cbm_mcp_text_result("git status returned a malformed path record", true);
+        }
+        return cbm_mcp_text_result(
+            status_run != 0 ? "git status failed: the contained command could not complete"
+                            : "git status failed while collecting changed paths",
+            true);
+    }
+    if (file_count > 1) {
+        qsort(files, (size_t)file_count, sizeof(*files), detect_changed_path_compare);
+    }
+
+    /* Per-symbol impact page size. Engine saturation makes the reported total
+     * an explicit lower bound, while impact_offset continues every materialized
+     * row without identifier truncation. */
     int imp_limit = cbm_mcp_get_int_arg(args, "limit", MCP_DEFAULT_IMPACT_LIMIT);
     if (imp_limit < 1) {
         imp_limit = 1;
@@ -10374,12 +14486,43 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     if (imp_limit > MCP_BFS_LIMIT_MAX) {
         imp_limit = MCP_BFS_LIMIT_MAX;
     }
-
-    /* Collect changed file paths into a C array (drives seeds, the rollup, and
-     * both output encodings). */
-    char **files = NULL;
-    int file_count = 0;
-    int file_cap = 0;
+    int impact_offset = cbm_mcp_get_int_arg(args, "impact_offset", 0);
+    if (impact_offset < 0) {
+        impact_offset = 0;
+    }
+    int changed_limit = cbm_mcp_get_int_arg(args, "changed_limit", 20);
+    int changed_offset = cbm_mcp_get_int_arg(args, "changed_offset", 0);
+    if (changed_limit < 0) {
+        changed_limit = 0;
+    } else if (changed_limit > MCP_BFS_LIMIT_MAX) {
+        changed_limit = MCP_BFS_LIMIT_MAX;
+    }
+    if (changed_offset < 0) {
+        changed_offset = 0;
+    }
+    int module_limit = cbm_mcp_get_int_arg(args, "module_limit", 20);
+    int module_offset = cbm_mcp_get_int_arg(args, "module_offset", 0);
+    if (module_limit < 0) {
+        module_limit = 0;
+    } else if (module_limit > DETECT_MODCAP) {
+        module_limit = DETECT_MODCAP;
+    }
+    if (module_offset < 0) {
+        module_offset = 0;
+    }
+    int max_output_tokens = cbm_mcp_get_int_arg(args, "max_output_tokens", 3200);
+    if (max_output_tokens < 128) {
+        max_output_tokens = 128;
+    } else if (max_output_tokens > 1000000) {
+        max_output_tokens = 1000000;
+    }
+    char *impact_cursor_arg = cbm_mcp_get_string_arg(args, "impact_cursor");
+    char *changed_cursor_arg = cbm_mcp_get_string_arg(args, "changed_cursor");
+    char *module_cursor_arg = cbm_mcp_get_string_arg(args, "module_cursor");
+    uint64_t detect_qhash = detect_params_hash(project, base_branch,
+                                               want_symbols ? "impact" : "files", direction, depth);
+
+    /* Changed paths drive traversal seeds and both output encodings. */
     int64_t *seeds = NULL;
     int seed_count = 0;
     int seed_cap = 0;
@@ -10405,21 +14548,23 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         char hunk_cmd[CBM_SZ_2K];
 #ifdef _WIN32
         snprintf(hunk_cmd, sizeof(hunk_cmd),
-                 "git -C \"%s\" diff --unified=0 \"%s\"...HEAD 2>NUL & "
-                 "git -C \"%s\" diff --unified=0 2>NUL",
-                 root_path, base_branch, root_path);
+                 "git -C \"%s\" diff --unified=0 \"%s\" \"%s\" -- 2>NUL && "
+                 "git -C \"%s\" diff --unified=0 -- 2>NUL",
+                 root_path, merge_base, head_oid, root_path);
 #else
         snprintf(hunk_cmd, sizeof(hunk_cmd),
-                 "{ git -C '%s' diff --unified=0 '%s'...HEAD 2>/dev/null; "
-                 "git -C '%s' diff --unified=0 2>/dev/null; }",
-                 root_path, base_branch, root_path);
+                 "git -C '%s' diff --unified=0 '%s' '%s' -- 2>/dev/null && "
+                 "git -C '%s' diff --unified=0 -- 2>/dev/null",
+                 root_path, merge_base, head_oid, root_path);
 #endif
         char hunk_output_path[CBM_SZ_2K] = {0};
         cbm_proc_result_t hunk_result = {0};
         int hunk_run =
             mcp_run_shell_command_cancellable(srv, hunk_cmd, hunk_output_path, &hunk_result);
         bool hunk_cancelled = hunk_result.cancellation_requested || mcp_request_cancelled(srv);
-        FILE *hfp = (!hunk_cancelled && hunk_run == 0) ? cbm_fopen(hunk_output_path, "rb") : NULL;
+        FILE *hfp = (!hunk_cancelled && hunk_run == 0 && hunk_result.exit_code == 0)
+                        ? cbm_fopen(hunk_output_path, "rb")
+                        : NULL;
         if (hfp) {
             (void)fseek(hfp, 0, SEEK_END);
             long hsz = ftell(hfp);
@@ -10452,121 +14597,133 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         if (hunk_output_path[0]) {
             (void)cbm_unlink(hunk_output_path);
         }
-    }
-
-    char line[CBM_SZ_1K];
-    while (fgets(line, sizeof(line), fp)) {
-        size_t len = strlen(line);
-        while (len > 0 && (line[len - SKIP_ONE] == '\n' || line[len - SKIP_ONE] == '\r')) {
-            line[--len] = '\0';
-        }
-        if (len == 0) {
-            continue;
-        }
-        /* Strip the `git status --porcelain` 2-char code + space; for a rename
-         * ("R  old -> new") keep the destination path. */
-        char *path_line = line;
-        if (len > PAIR_LEN && line[PAIR_LEN] == ' ' && strchr(" MADRCU?!", line[0]) &&
-            strchr(" MADRCU?!", line[1])) {
-            path_line = line + PAIR_LEN + SKIP_ONE;
-            char *arrow = strstr(path_line, " -> ");
-            if (arrow) {
-                enum { ARROW_LEN = 4 };
-                path_line = arrow + ARROW_LEN;
-            }
-        }
-        if (path_line[0] == '\0') {
-            continue;
-        }
-        /* Dedup: the three git sources are sorted+unioned on POSIX but not on
-         * Windows (separate commands), and a path can repeat. */
-        bool dup = false;
+        /* Hunk parsing is deliberately best-effort, but path collection is not.
+         * Seed after both are complete so every exact path uses the same scoping
+         * decision. */
         for (int i = 0; i < file_count; i++) {
-            if (strcmp(files[i], path_line) == 0) {
-                dup = true;
-                break;
-            }
-        }
-        if (dup) {
-            continue;
-        }
-        if (file_count >= file_cap) {
-            file_cap = file_cap ? file_cap * 2 : 16;
-            files = safe_realloc(files, (size_t)file_cap * sizeof(char *));
-        }
-        files[file_count++] = heap_strdup(path_line);
-        if (want_symbols) {
-            detect_collect_seeds(store, project, path_line, hunks, hunk_count, &seeds, &seed_count,
+            detect_collect_seeds(store, project, files[i], hunks, hunk_count, &seeds, &seed_count,
                                  &seed_cap);
         }
     }
-    (void)fclose(fp);
-    (void)cbm_unlink(output_path);
-    int git_status = git_result.exit_code;
 
-    /* merge-base SHA: the exact commit the diff is measured against, so the
-     * result is reproducible even as base_branch advances. Best-effort. */
-    char merge_base[64] = "";
-    {
-        char mbcmd[CBM_SZ_2K];
-#ifdef _WIN32
-        snprintf(mbcmd, sizeof(mbcmd), "git -C \"%s\" merge-base \"%s\" HEAD 2>NUL", root_path,
-                 base_branch);
-#else
-        snprintf(mbcmd, sizeof(mbcmd), "git -C '%s' merge-base '%s' HEAD 2>/dev/null", root_path,
-                 base_branch);
-#endif
-        char mb_output_path[CBM_SZ_2K] = {0};
-        cbm_proc_result_t mb_result = {0};
-        int mb_run = mcp_run_shell_command_cancellable(srv, mbcmd, mb_output_path, &mb_result);
-        bool mb_cancelled = mb_result.cancellation_requested || mcp_request_cancelled(srv);
-        bool mb_containment_failed = mb_run != 0 && mb_output_path[0] != '\0';
-        FILE *mbfp =
-            mb_run == 0 && mb_result.exit_code == 0 ? cbm_fopen(mb_output_path, "rb") : NULL;
-        if (mbfp && !mb_cancelled) {
-            if (fgets(merge_base, sizeof(merge_base), mbfp)) {
-                size_t l = strlen(merge_base);
-                while (l > 0 && (merge_base[l - 1] == '\n' || merge_base[l - 1] == '\r')) {
-                    merge_base[--l] = '\0';
-                }
+    /* The impact traversal: ONE multi-source BFS over all seeds. */
+    cbm_traverse_result_t impact = {0};
+    bool engine_saturated = false;
+    if (want_symbols && seed_count > 0) {
+        (void)cbm_store_bfs_multi(store, seeds, seed_count, direction, NULL, 0, depth,
+                                  MCP_BFS_LIMIT_MAX, &impact, &engine_saturated);
+    }
+
+    detect_module_row_t *modules = NULL;
+    int nmods = 0;
+    int module_overflow = 0;
+    if (want_symbols && impact.visited_count > 0) {
+        modules = calloc(DETECT_MODCAP, sizeof(*modules));
+        if (modules) {
+            nmods = detect_module_rollup(&impact, modules, &module_overflow);
+        }
+    }
+    /* Overflow is represented as one explicit aggregate row. This is the exact
+     * number of pageable rollup rows for the materialized impact set; its
+     * relation becomes `gte` if traversal hit the engine ceiling. */
+    int module_total = nmods + (module_overflow > 0 ? 1 : 0);
+    const char *cursor_error = NULL;
+    char detect_snapshot[33] = "";
+    bool detect_snapshot_complete = detect_snapshot_fingerprint(
+        srv, root_path, head_oid, base_oid, merge_base, generation, files, file_count, &impact,
+        modules, nmods, module_overflow, detect_snapshot);
+
+    detect_cursor_t decoded_cursor = {0};
+    bool cursor_supplied = (changed_cursor_arg && changed_cursor_arg[0]) ||
+                           (impact_cursor_arg && impact_cursor_arg[0]) ||
+                           (module_cursor_arg && module_cursor_arg[0]);
+    if (cursor_supplied && !detect_snapshot_complete) {
+        cursor_error = "snapshot_unavailable: changed file bytes could not be fingerprinted — "
+                       "rerun without the cursor after the files are readable";
+    }
+    if (!cursor_error && changed_cursor_arg && changed_cursor_arg[0]) {
+        if (changed_offset != 0) {
+            cursor_error = "cursor_params_mismatch: changed_cursor cannot be combined with a "
+                           "nonzero changed_offset";
+        } else {
+            cursor_error = detect_cursor_decode(changed_cursor_arg, 'c', detect_snapshot,
+                                                detect_qhash, &decoded_cursor);
+            if (!cursor_error) {
+                changed_offset = decoded_cursor.offset;
             }
         }
-        if (mbfp) {
-            (void)fclose(mbfp);
-        }
-        if (mb_output_path[0]) {
-            (void)cbm_unlink(mb_output_path);
+    }
+    if (!cursor_error && impact_cursor_arg && impact_cursor_arg[0]) {
+        if (impact_offset != 0) {
+            cursor_error = "cursor_params_mismatch: impact_cursor cannot be combined with a "
+                           "nonzero impact_offset";
+        } else {
+            cursor_error = detect_cursor_decode(impact_cursor_arg, 'i', detect_snapshot,
+                                                detect_qhash, &decoded_cursor);
+            if (!cursor_error) {
+                impact_offset = decoded_cursor.offset;
+            }
         }
-        if (mb_cancelled || mb_containment_failed) {
-            for (int i = 0; i < file_count; i++) {
-                free(files[i]);
+    }
+    if (!cursor_error && module_cursor_arg && module_cursor_arg[0]) {
+        if (module_offset != 0) {
+            cursor_error = "cursor_params_mismatch: module_cursor cannot be combined with a "
+                           "nonzero module_offset";
+        } else {
+            cursor_error = detect_cursor_decode(module_cursor_arg, 'm', detect_snapshot,
+                                                detect_qhash, &decoded_cursor);
+            if (!cursor_error) {
+                module_offset = decoded_cursor.offset;
             }
-            free(files);
-            free(seeds);
-            free(hunks);
-            free(direction);
-            free(root_path);
-            free(project);
-            free(base_branch);
-            free(scope);
-            return cbm_mcp_text_result(
-                mb_cancelled ? "detect_changes cancelled for this request"
-                             : "git merge-base failed: the contained command could not complete",
-                true);
         }
     }
-
-    /* The impact traversal: ONE multi-source BFS over all seeds. */
-    cbm_traverse_result_t impact = {0};
-    bool truncated = false;
-    if (want_symbols && seed_count > 0) {
-        (void)cbm_store_bfs_multi(store, seeds, seed_count, direction, NULL, 0, depth,
-                                  MCP_BFS_LIMIT_MAX, &impact, &truncated);
+    if (cursor_error) {
+        cbm_store_traverse_free(&impact);
+        detect_module_rollup_free(modules, nmods);
+        for (int i = 0; i < file_count; i++) {
+            free(files[i]);
+        }
+        free(files);
+        free(seeds);
+        free(hunks);
+        free(impact_cursor_arg);
+        free(changed_cursor_arg);
+        free(module_cursor_arg);
+        free(direction);
+        free(root_path);
+        free(project);
+        free(base_branch);
+        free(scope);
+        return cbm_mcp_text_result(cursor_error, true);
     }
 
-    bool is_error = (git_status != 0 && file_count == 0);
+    int changed_start = changed_offset < file_count ? changed_offset : file_count;
+    int changed_returned = file_count - changed_start;
+    if (changed_returned > changed_limit) {
+        changed_returned = changed_limit;
+    }
+    int module_start = module_offset < module_total ? module_offset : module_total;
+    int module_returned = module_total - module_start;
+    if (module_returned > module_limit) {
+        module_returned = module_limit;
+    }
+    int imp_start = impact_offset < impact.visited_count ? impact_offset : impact.visited_count;
+    int imp_returned = impact.visited_count - imp_start;
+    if (imp_returned > imp_limit) {
+        imp_returned = imp_limit;
+    }
+    size_t output_budget_bytes =
+        (size_t)max_output_tokens * (size_t)MCP_OUTPUT_BYTES_PER_TOKEN_ESTIMATE;
+    bool output_budget_hit = false;
+    bool output_budget_floor_exceeded = false;
     char *out_str = NULL;
 
+render_detect_output:;
+    bool changed_has_more = changed_start + changed_returned < file_count;
+    bool impacted_has_more = want_symbols && imp_start + imp_returned < impact.visited_count;
+    bool module_has_more = want_symbols && module_start + module_returned < module_total;
+    bool response_truncated = engine_saturated || output_budget_hit || changed_has_more ||
+                              impacted_has_more || module_has_more;
     if (!legacy_json) {
         cbm_sb_t sb;
         cbm_sb_init(&sb);
@@ -10575,54 +14732,118 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             cbm_tree_scalar_str(&sb, "merge_base", merge_base);
         }
         cbm_tree_scalar_str(&sb, "direction", direction);
-        if (is_error) {
-            char hint_buf[CBM_SZ_256];
-            snprintf(hint_buf, sizeof(hint_buf),
-                     "git diff exited with status %d. Check that branch '%s' exists.", git_status,
-                     base_branch);
-            cbm_tree_scalar_str(&sb, "hint", hint_buf);
-        }
-        /* changed files (the git result) */
-        char cf[CBM_SZ_64];
-        snprintf(cf, sizeof(cf), "changed_files: %d\n", file_count);
-        cbm_sb_append(&sb, cf);
-        for (int i = 0; i < file_count; i++) {
-            cbm_sb_append(&sb, "  ");
-            cbm_sb_append(&sb, files[i]);
-            cbm_sb_append(&sb, "\n");
+        if (output_budget_hit) {
+            cbm_tree_scalar_str(&sb, "truncation_reason", "output_budget");
+            cbm_tree_scalar_int(&sb, "max_output_bytes", (long long)output_budget_bytes);
+        }
+        if (output_budget_floor_exceeded) {
+            cbm_tree_scalar_bool(&sb, "output_budget_floor_exceeded", true);
+        }
+        if (engine_saturated) {
+            cbm_tree_scalar_bool(&sb, "engine_saturated", true);
+        }
+        if (!detect_snapshot_complete) {
+            cbm_tree_scalar_bool(&sb, "snapshot_cursor_unavailable", true);
+        }
+        /* Changed files are independently pageable: traversal still used every
+         * file, so paging affects presentation only, never the graph answer. */
+        cbm_tree_scalar_int(&sb, "changed_total", file_count);
+        cbm_tree_scalar_int(&sb, "changed_returned", changed_returned);
+        cbm_tree_scalar_bool(&sb, "changed_has_more", changed_has_more);
+        if (changed_has_more && changed_returned > 0) {
+            cbm_tree_scalar_int(&sb, "changed_next_offset", changed_start + changed_returned);
+            if (detect_snapshot_complete) {
+                char cursor[80];
+                detect_cursor_encode('c', detect_snapshot, detect_qhash,
+                                     changed_start + changed_returned, cursor);
+                cbm_tree_scalar_str(&sb, "changed_next_cursor", cursor);
+            }
+        } else if (changed_has_more) {
+            cbm_tree_scalar_bool(&sb,
+                                 changed_limit == 0 ? "changed_continuation_requires_positive_limit"
+                                                    : "changed_continuation_requires_higher_budget",
+                                 true);
+        }
+        static const char *const changed_columns[] = {"path"};
+        const char **changed_cells =
+            changed_returned > 0 ? calloc((size_t)changed_returned, sizeof(*changed_cells)) : NULL;
+        if (changed_returned == 0 || changed_cells) {
+            for (int row = 0; row < changed_returned; row++) {
+                changed_cells[row] = files[changed_start + row];
+            }
+            static const bool changed_string_columns[] = {true};
+            static const bool changed_prefix_columns[] = {true};
+            cbm_tree_table_rows_profiled(&sb, "changed_files", changed_returned, changed_columns, 1,
+                                         changed_cells, changed_string_columns,
+                                         changed_prefix_columns);
+        } else {
+            cbm_tree_table_header(&sb, "changed_files", 0, changed_columns, 1);
+            cbm_tree_scalar_str(&sb, "changed_files_render_error", "out_of_memory");
         }
+        free(changed_cells);
         cbm_tree_scalar_int(&sb, "seed_symbols", seed_count);
         if (want_symbols) {
-            detect_emit_impacted_tree(&sb, &impact, imp_limit);
-            /* module rollup: a quotient view of the blast radius */
-            if (impact.visited_count > 0) {
-                cbm_sb_append(&sb, "impacted_modules: (rows: module count)\n");
-                char (*mods)[CBM_SZ_128] = malloc(DETECT_MODCAP * CBM_SZ_128);
-                int *mcnt = malloc(DETECT_MODCAP * sizeof(int));
-                if (mods && mcnt) {
-                    int overflow = 0;
-                    int nmods = detect_module_rollup(&impact, mods, mcnt, &overflow);
-                    for (int j = 0; j < nmods; j++) {
-                        char mrow[CBM_SZ_256];
-                        snprintf(mrow, sizeof(mrow), "  %s %d\n", mods[j], mcnt[j]);
-                        cbm_sb_append(&sb, mrow);
-                    }
-                    if (overflow > 0) {
-                        char orow[CBM_SZ_128];
-                        snprintf(orow, sizeof(orow), "  (other) %d\n", overflow);
-                        cbm_sb_append(&sb, orow);
-                    }
+            detect_emit_impacted_tree(&sb, &impact, imp_start, imp_returned, engine_saturated);
+            if (detect_snapshot_complete && imp_start + imp_returned < impact.visited_count &&
+                imp_returned > 0) {
+                char cursor[80];
+                detect_cursor_encode('i', detect_snapshot, detect_qhash, imp_start + imp_returned,
+                                     cursor);
+                cbm_tree_scalar_str(&sb, "impacted_next_cursor", cursor);
+            }
+            /* module rollup: independently pageable, while counts are still
+             * computed from the complete impact set. */
+            cbm_tree_scalar_int(&sb, "module_total", module_total);
+            cbm_tree_scalar_str(&sb, "module_total_relation", engine_saturated ? "gte" : "eq");
+            cbm_tree_scalar_int(&sb, "module_returned", module_returned);
+            cbm_tree_scalar_bool(&sb, "module_has_more", module_has_more);
+            if (module_has_more && module_returned > 0) {
+                cbm_tree_scalar_int(&sb, "module_next_offset", module_start + module_returned);
+                if (detect_snapshot_complete) {
+                    char cursor[80];
+                    detect_cursor_encode('m', detect_snapshot, detect_qhash,
+                                         module_start + module_returned, cursor);
+                    cbm_tree_scalar_str(&sb, "module_next_cursor", cursor);
+                }
+            } else if (module_has_more) {
+                cbm_tree_scalar_bool(&sb,
+                                     module_limit == 0
+                                         ? "module_continuation_requires_positive_limit"
+                                         : "module_continuation_requires_higher_budget",
+                                     true);
+            }
+            static const char *const columns[] = {"module", "count"};
+            const char **cells =
+                module_returned > 0 ? calloc((size_t)module_returned * 2U, sizeof(*cells)) : NULL;
+            char (*count_text)[32] =
+                module_returned > 0 ? calloc((size_t)module_returned, sizeof(*count_text)) : NULL;
+            if (module_returned == 0 || (cells && count_text)) {
+                for (int row = 0; row < module_returned; row++) {
+                    int j = module_start + row;
+                    cells[(size_t)row * 2U] = j < nmods ? modules[j].name : "(other)";
+                    snprintf(count_text[row], sizeof(count_text[row]), "%d",
+                             j < nmods ? modules[j].count : module_overflow);
+                    cells[(size_t)row * 2U + 1U] = count_text[row];
                 }
-                free(mods);
-                free(mcnt);
+                static const bool string_cols[] = {true, false};
+                static const bool prefix_cols[] = {true, false};
+                cbm_tree_table_rows_profiled(&sb, "impacted_modules", module_returned, columns, 2,
+                                             cells, string_cols, prefix_cols);
+            } else {
+                cbm_tree_table_header(&sb, "impacted_modules", 0, columns, 2);
+                cbm_tree_scalar_str(&sb, "module_render_error", "out_of_memory");
             }
-            if (truncated) {
-                cbm_tree_scalar_bool(&sb, "truncated", true);
+            free(count_text);
+            free(cells);
+            if (engine_saturated) {
                 cbm_tree_scalar_str(&sb, "hint",
                                     "impact hit the safety ceiling — narrow with a lower "
                                     "'depth' or a smaller diff");
             }
         }
+        if (response_truncated) {
+            cbm_tree_scalar_bool(&sb, "truncated", true);
+        }
         out_str = cbm_sb_finish(&sb);
     } else {
         /* format:"json" = json-stringified tree: same model, structured. */
@@ -10634,17 +14855,50 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             yyjson_mut_obj_add_strcpy(doc, root_obj, "merge_base", merge_base);
         }
         yyjson_mut_obj_add_strcpy(doc, root_obj, "direction", direction);
+        if (output_budget_hit) {
+            yyjson_mut_obj_add_str(doc, root_obj, "truncation_reason", "output_budget");
+            yyjson_mut_obj_add_uint(doc, root_obj, "max_output_bytes", output_budget_bytes);
+        }
+        if (output_budget_floor_exceeded) {
+            yyjson_mut_obj_add_bool(doc, root_obj, "output_budget_floor_exceeded", true);
+        }
+        if (engine_saturated) {
+            yyjson_mut_obj_add_bool(doc, root_obj, "engine_saturated", true);
+        }
+        if (!detect_snapshot_complete) {
+            yyjson_mut_obj_add_bool(doc, root_obj, "snapshot_cursor_unavailable", true);
+        }
+        yyjson_mut_obj_add_int(doc, root_obj, "changed_total", file_count);
+        yyjson_mut_obj_add_int(doc, root_obj, "changed_returned", changed_returned);
+        yyjson_mut_obj_add_bool(doc, root_obj, "changed_has_more", changed_has_more);
+        if (changed_has_more && changed_returned > 0) {
+            yyjson_mut_obj_add_int(doc, root_obj, "changed_next_offset",
+                                   changed_start + changed_returned);
+            if (detect_snapshot_complete) {
+                char cursor[80];
+                detect_cursor_encode('c', detect_snapshot, detect_qhash,
+                                     changed_start + changed_returned, cursor);
+                yyjson_mut_obj_add_strcpy(doc, root_obj, "changed_next_cursor", cursor);
+            }
+        } else if (changed_has_more) {
+            yyjson_mut_obj_add_bool(doc, root_obj,
+                                    changed_limit == 0
+                                        ? "changed_continuation_requires_positive_limit"
+                                        : "changed_continuation_requires_higher_budget",
+                                    true);
+        }
         yyjson_mut_val *cf = yyjson_mut_arr(doc);
-        for (int i = 0; i < file_count; i++) {
+        for (int i = changed_start; i < changed_start + changed_returned; i++) {
             yyjson_mut_arr_add_strcpy(doc, cf, files[i]);
         }
         yyjson_mut_obj_add_val(doc, root_obj, "changed_files", cf);
         yyjson_mut_obj_add_int(doc, root_obj, "seed_symbols", seed_count);
         yyjson_mut_obj_add_int(doc, root_obj, "impacted_total", impact.visited_count);
-        int imp_shown = impact.visited_count < imp_limit ? impact.visited_count : imp_limit;
-        yyjson_mut_obj_add_int(doc, root_obj, "impacted_shown", imp_shown);
+        yyjson_mut_obj_add_str(doc, root_obj, "impacted_total_relation",
+                               engine_saturated ? "gte" : "eq");
+        yyjson_mut_obj_add_int(doc, root_obj, "impacted_shown", imp_returned);
         yyjson_mut_val *imp = yyjson_mut_arr(doc);
-        for (int i = 0; i < imp_shown; i++) {
+        for (int i = imp_start; i < imp_start + imp_returned; i++) {
             yyjson_mut_val *o = yyjson_mut_obj(doc);
             yyjson_mut_obj_add_strcpy(
                 doc, o, "qn",
@@ -10658,57 +14912,140 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             yyjson_mut_arr_add_val(imp, o);
         }
         yyjson_mut_obj_add_val(doc, root_obj, "impacted", imp);
-        /* Model parity with the tree encoding: the complete module rollup. */
-        if (impact.visited_count > 0) {
-            char (*mods)[CBM_SZ_128] = malloc(DETECT_MODCAP * CBM_SZ_128);
-            int *mcnt = malloc(DETECT_MODCAP * sizeof(int));
-            if (mods && mcnt) {
-                int overflow = 0;
-                int nmods = detect_module_rollup(&impact, mods, mcnt, &overflow);
-                yyjson_mut_val *rollup = yyjson_mut_arr(doc);
-                for (int j = 0; j < nmods; j++) {
-                    yyjson_mut_val *o = yyjson_mut_obj(doc);
-                    yyjson_mut_obj_add_strcpy(doc, o, "module", mods[j]);
-                    yyjson_mut_obj_add_int(doc, o, "count", mcnt[j]);
-                    yyjson_mut_arr_add_val(rollup, o);
+        yyjson_mut_obj_add_bool(doc, root_obj, "impacted_has_more", impacted_has_more);
+        if (impacted_has_more && imp_returned > 0) {
+            yyjson_mut_obj_add_int(doc, root_obj, "impacted_next_offset", imp_start + imp_returned);
+            if (detect_snapshot_complete) {
+                char cursor[80];
+                detect_cursor_encode('i', detect_snapshot, detect_qhash, imp_start + imp_returned,
+                                     cursor);
+                yyjson_mut_obj_add_strcpy(doc, root_obj, "impacted_next_cursor", cursor);
+            }
+        } else if (impacted_has_more) {
+            yyjson_mut_obj_add_bool(doc, root_obj, "impacted_continuation_requires_higher_budget",
+                                    true);
+        }
+        /* Model parity with the tree encoding: complete totals, paged rows. */
+        if (want_symbols) {
+            yyjson_mut_obj_add_int(doc, root_obj, "module_total", module_total);
+            yyjson_mut_obj_add_str(doc, root_obj, "module_total_relation",
+                                   engine_saturated ? "gte" : "eq");
+            yyjson_mut_obj_add_int(doc, root_obj, "module_returned", module_returned);
+            yyjson_mut_obj_add_bool(doc, root_obj, "module_has_more", module_has_more);
+            if (module_has_more && module_returned > 0) {
+                yyjson_mut_obj_add_int(doc, root_obj, "module_next_offset",
+                                       module_start + module_returned);
+                if (detect_snapshot_complete) {
+                    char cursor[80];
+                    detect_cursor_encode('m', detect_snapshot, detect_qhash,
+                                         module_start + module_returned, cursor);
+                    yyjson_mut_obj_add_strcpy(doc, root_obj, "module_next_cursor", cursor);
                 }
-                if (overflow > 0) {
-                    yyjson_mut_val *o = yyjson_mut_obj(doc);
-                    yyjson_mut_obj_add_strcpy(doc, o, "module", "(other)");
-                    yyjson_mut_obj_add_int(doc, o, "count", overflow);
-                    yyjson_mut_arr_add_val(rollup, o);
+            } else if (module_has_more) {
+                yyjson_mut_obj_add_bool(doc, root_obj,
+                                        module_limit == 0
+                                            ? "module_continuation_requires_positive_limit"
+                                            : "module_continuation_requires_higher_budget",
+                                        true);
+            }
+            yyjson_mut_val *rollup = yyjson_mut_arr(doc);
+            for (int j = module_start; j < module_start + module_returned; j++) {
+                yyjson_mut_val *o = yyjson_mut_obj(doc);
+                if (j < nmods) {
+                    yyjson_mut_obj_add_strcpy(doc, o, "module", modules[j].name);
+                    yyjson_mut_obj_add_int(doc, o, "count", modules[j].count);
+                } else {
+                    yyjson_mut_obj_add_str(doc, o, "module", "(other)");
+                    yyjson_mut_obj_add_int(doc, o, "count", module_overflow);
                 }
-                yyjson_mut_obj_add_val(doc, root_obj, "impacted_modules", rollup);
+                yyjson_mut_arr_add_val(rollup, o);
             }
-            free(mods);
-            free(mcnt);
-        }
-        yyjson_mut_obj_add_bool(doc, root_obj, "truncated", truncated);
-        if (is_error) {
-            char hint_buf[CBM_SZ_256];
-            snprintf(hint_buf, sizeof(hint_buf),
-                     "git diff exited with status %d. Check that branch '%s' exists.", git_status,
-                     base_branch);
-            yyjson_mut_obj_add_strcpy(doc, root_obj, "hint", hint_buf);
+            yyjson_mut_obj_add_val(doc, root_obj, "impacted_modules", rollup);
         }
+        yyjson_mut_obj_add_bool(doc, root_obj, "truncated", response_truncated);
         out_str = yy_doc_to_str(doc);
         yyjson_mut_doc_free(doc);
     }
 
+    /* Exact serialized-size check with semantic reductions only. Low-value
+     * rollups and file names yield as whole sections before graph rows. The
+     * continuations above remain valid even when a requested page is omitted
+     * by this soft budget. */
+    if (out_str && strlen(out_str) > output_budget_bytes) {
+        output_budget_hit = true;
+        if (module_returned > 0) {
+            module_returned = 0;
+        } else if (changed_returned > 0) {
+            changed_returned = 0;
+        } else if (imp_returned > 0) {
+            /* Prefix-directory activation can make N compact rows smaller
+             * than N-1 direct rows. Probe every smaller whole-row prefix so
+             * the response retains the largest page that actually fits. */
+            imp_returned--;
+        } else if (!output_budget_floor_exceeded) {
+            output_budget_floor_exceeded = true;
+        } else {
+            free(out_str);
+            out_str = NULL;
+            if (!legacy_json) {
+                cbm_sb_t floor;
+                cbm_sb_init(&floor);
+                cbm_tree_scalar_str(&floor, "truncation_reason", "output_budget");
+                cbm_tree_scalar_bool(&floor, "truncated", true);
+                cbm_tree_scalar_bool(&floor, "output_budget_floor_exceeded", true);
+                if (engine_saturated) {
+                    cbm_tree_scalar_bool(&floor, "engine_saturated", true);
+                }
+                cbm_tree_scalar_int(&floor, "max_output_bytes", (long long)output_budget_bytes);
+                cbm_tree_scalar_str(&floor, "hint",
+                                    "mandatory detect_changes metadata exceeds the budget; raise "
+                                    "max_output_tokens (no path or identifier was sliced)");
+                out_str = cbm_sb_finish(&floor);
+            } else {
+                yyjson_mut_doc *floor_doc = yyjson_mut_doc_new(NULL);
+                yyjson_mut_val *floor = yyjson_mut_obj(floor_doc);
+                yyjson_mut_doc_set_root(floor_doc, floor);
+                yyjson_mut_obj_add_str(floor_doc, floor, "truncation_reason", "output_budget");
+                yyjson_mut_obj_add_bool(floor_doc, floor, "truncated", true);
+                yyjson_mut_obj_add_bool(floor_doc, floor, "output_budget_floor_exceeded", true);
+                if (engine_saturated) {
+                    yyjson_mut_obj_add_bool(floor_doc, floor, "engine_saturated", true);
+                }
+                yyjson_mut_obj_add_uint(floor_doc, floor, "max_output_bytes", output_budget_bytes);
+                yyjson_mut_obj_add_str(
+                    floor_doc, floor, "hint",
+                    "mandatory detect_changes metadata exceeds the budget; raise "
+                    "max_output_tokens (no path or identifier was sliced)");
+                out_str = yy_doc_to_str(floor_doc);
+                yyjson_mut_doc_free(floor_doc);
+            }
+            goto detect_output_done;
+        }
+        free(out_str);
+        out_str = NULL;
+        goto render_detect_output;
+    }
+
+detect_output_done:
+
     cbm_store_traverse_free(&impact);
+    detect_module_rollup_free(modules, nmods);
     for (int i = 0; i < file_count; i++) {
         free(files[i]);
     }
     free(files);
     free(seeds);
     free(hunks);
+    free(impact_cursor_arg);
+    free(changed_cursor_arg);
+    free(module_cursor_arg);
     free(direction);
     free(root_path);
     free(project);
     free(base_branch);
     free(scope);
 
-    char *result = cbm_mcp_text_result(out_str, is_error);
+    char *result = cbm_mcp_text_result(out_str, false);
     free(out_str);
     return result;
 }
@@ -10728,13 +15065,13 @@ static void adr_list_sections_from_content(yyjson_mut_doc *doc, yyjson_mut_val *
             linelen--;
         }
         if (linelen > 0 && p[0] == '#') {
-            char hdr[CBM_SZ_1K];
-            if (linelen >= sizeof(hdr)) {
-                linelen = sizeof(hdr) - SKIP_ONE;
+            char *header = cbm_strndup(p, linelen);
+            if (header) {
+                yyjson_mut_arr_add_strcpy(doc, sections, header);
+                free(header);
+            } else {
+                yyjson_mut_arr_add_str(doc, sections, "(out-of-memory)");
             }
-            memcpy(hdr, p, linelen);
-            hdr[linelen] = '\0';
-            yyjson_mut_arr_add_strcpy(doc, sections, hdr);
         }
         if (!eol) {
             break;
@@ -10744,6 +15081,117 @@ static void adr_list_sections_from_content(yyjson_mut_doc *doc, yyjson_mut_val *
     yyjson_mut_obj_add_val(doc, root_obj, "sections", sections);
 }
 
+static int adr_line_count(const char *content) {
+    if (!content || !content[0]) {
+        return 0;
+    }
+    int lines = 1;
+    for (const char *p = content; *p; p++) {
+        if (*p == '\n' && p[1]) {
+            lines++;
+        }
+    }
+    return lines;
+}
+
+typedef struct {
+    const char *text;
+    size_t text_len;
+    int level;
+    int start_line;
+    int end_line;
+} adr_heading_row_t;
+
+static int adr_collect_headings(const char *content, adr_heading_row_t **out_rows,
+                                int *out_total_lines) {
+    *out_rows = NULL;
+    *out_total_lines = adr_line_count(content);
+    if (!content || !content[0]) {
+        return 0;
+    }
+    int capacity = 16;
+    int count = 0;
+    adr_heading_row_t *rows = malloc((size_t)capacity * sizeof(*rows));
+    if (!rows) {
+        return 0;
+    }
+    const char *p = content;
+    int line = 1;
+    while (*p) {
+        const char *eol = strchr(p, '\n');
+        const char *line_end = eol ? eol : p + strlen(p);
+        const char *trimmed_end = line_end;
+        if (trimmed_end > p && trimmed_end[-1] == '\r') {
+            trimmed_end--;
+        }
+        int level = 0;
+        while (p + level < trimmed_end && p[level] == '#') {
+            level++;
+        }
+        if (level > 0 && level <= 6 && p + level < trimmed_end && p[level] == ' ') {
+            if (count == capacity) {
+                capacity *= 2;
+                rows = safe_realloc(rows, (size_t)capacity * sizeof(*rows));
+            }
+            if (count > 0) {
+                rows[count - 1].end_line = line - 1;
+            }
+            rows[count++] = (adr_heading_row_t){.text = p,
+                                                .text_len = (size_t)(trimmed_end - p),
+                                                .level = level,
+                                                .start_line = line,
+                                                .end_line = *out_total_lines};
+        }
+        if (!eol) {
+            break;
+        }
+        p = eol + 1;
+        line++;
+    }
+    *out_rows = rows;
+    return count;
+}
+
+static void adr_add_outline(yyjson_mut_doc *doc, yyjson_mut_val *root_obj, const char *content,
+                            int offset, int limit) {
+    int total_lines = 0;
+    adr_heading_row_t *rows = NULL;
+    int total = adr_collect_headings(content, &rows, &total_lines);
+    if (offset < 0) {
+        offset = 0;
+    }
+    if (offset > total) {
+        offset = total;
+    }
+    int returned = total - offset;
+    if (returned > limit) {
+        returned = limit;
+    }
+    yyjson_mut_obj_add_str(doc, root_obj, "mode", "outline");
+    yyjson_mut_val *headings = yyjson_mut_arr(doc);
+    for (int i = 0; i < returned; i++) {
+        const adr_heading_row_t *row = &rows[offset + i];
+        yyjson_mut_val *item = yyjson_mut_obj(doc);
+        yyjson_mut_obj_add_int(doc, item, "index", offset + i);
+        yyjson_mut_obj_add_strncpy(doc, item, "heading", row->text, row->text_len);
+        yyjson_mut_obj_add_int(doc, item, "level", row->level);
+        yyjson_mut_obj_add_int(doc, item, "start_line", row->start_line);
+        yyjson_mut_obj_add_int(doc, item, "end_line", row->end_line);
+        yyjson_mut_arr_add_val(headings, item);
+    }
+    yyjson_mut_obj_add_val(doc, root_obj, "headings", headings);
+    yyjson_mut_obj_add_int(doc, root_obj, "total_lines", total_lines);
+    yyjson_mut_obj_add_int(doc, root_obj, "sections_total", total);
+    yyjson_mut_obj_add_int(doc, root_obj, "sections_returned", returned);
+    bool has_more = offset + returned < total;
+    yyjson_mut_obj_add_bool(doc, root_obj, "sections_has_more", has_more);
+    if (has_more) {
+        yyjson_mut_obj_add_int(doc, root_obj, "next_section_offset", offset + returned);
+    }
+    yyjson_mut_obj_add_bool(doc, root_obj, "full_content_available", content != NULL);
+    free(rows);
+}
+
 /* Read the legacy file-based ADR (<root>/.codebase-memory/adr.md), used by
  * older versions. Returns a heap buffer (caller frees) or NULL if missing/
  * empty. Kept only to migrate old ADRs into the store (#256). */
@@ -10815,7 +15263,22 @@ static char *handle_manage_adr(cbm_mcp_server_t *srv, const char *args) {
     char *content = cbm_mcp_get_string_arg(args, "content");
 
     if (!mode_str) {
-        mode_str = heap_strdup("get");
+        mode_str = heap_strdup("outline");
+    }
+
+    bool valid_mode = strcmp(mode_str, "outline") == 0 || strcmp(mode_str, "get") == 0 ||
+                      strcmp(mode_str, "sections") == 0 || strcmp(mode_str, "update") == 0 ||
+                      strcmp(mode_str, "store") == 0;
+    if (!valid_mode) {
+        free(project);
+        free(mode_str);
+        free(content);
+        return cbm_mcp_text_result("invalid mode: use outline, get, sections, or update", true);
+    }
+    if ((strcmp(mode_str, "update") == 0 || strcmp(mode_str, "store") == 0) && !content) {
+        free(project);
+        free(mode_str);
+        return cbm_mcp_text_result("content is required for update", true);
     }
 
     /* `sections` used to be advertised as an input argument, but it was never
@@ -10958,9 +15421,20 @@ static char *handle_manage_adr(cbm_mcp_server_t *srv, const char *args) {
         }
     } else if (strcmp(mode_str, "sections") == 0) {
         adr_list_sections_from_content(doc, root_obj, adr_content);
+    } else if (strcmp(mode_str, "outline") == 0) {
+        int section_limit = cbm_mcp_get_int_arg(args, "section_limit", 50);
+        int section_offset = cbm_mcp_get_int_arg(args, "section_offset", 0);
+        if (section_limit < 1) {
+            section_limit = 1;
+        } else if (section_limit > 500) {
+            section_limit = 500;
+        }
+        adr_add_outline(doc, root_obj, adr_content, section_offset, section_limit);
     } else { /* get */
         if (adr_content) {
             yyjson_mut_obj_add_strcpy(doc, root_obj, "content", adr_content);
+            yyjson_mut_obj_add_int(doc, root_obj, "total_lines", adr_line_count(adr_content));
+            yyjson_mut_obj_add_bool(doc, root_obj, "content_complete", true);
         } else {
             yyjson_mut_obj_add_str(doc, root_obj, "content", "");
             yyjson_mut_obj_add_str(doc, root_obj, "status", "no_adr");
@@ -10970,6 +15444,7 @@ static char *handle_manage_adr(cbm_mcp_server_t *srv, const char *args) {
 
     char *json = yy_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
+    bool legacy_json_result = write_request || strcmp(mode_str, "sections") == 0;
     if (have_adr) {
         cbm_store_adr_free(&adr);
     }
@@ -10984,7 +15459,8 @@ static char *handle_manage_adr(cbm_mcp_server_t *srv, const char *args) {
     free(mode_str);
     free(content);
 
-    char *result = cbm_mcp_text_result(json, is_error);
+    char *result =
+        legacy_json_result ? cbm_mcp_text_result(json, is_error) : mcp_result_from_json(args, json);
     free(json);
     return result;
 }
@@ -11356,8 +15832,9 @@ bool cbm_mcp_jsonrpc_response_prepend_notice(char **response_io, const char *not
         yyjson_mut_doc_free(mutable_document);
         return false;
     }
-    char *replacement =
-        yyjson_mut_write(mutable_document, YYJSON_WRITE_ALLOW_INVALID_UNICODE, NULL);
+    /* The response was already normalized at its JSON-RPC boundary; preserve
+     * those strings while adding the valid UTF-8 notice. */
+    char *replacement = yyjson_mut_write(mutable_document, 0, NULL);
     yyjson_mut_doc_free(mutable_document);
     if (!replacement) {
         return false;
diff --git a/src/mcp/mcp_internal.h b/src/mcp/mcp_internal.h
index 313a4d1ce..4b1438c2a 100644
--- a/src/mcp/mcp_internal.h
+++ b/src/mcp/mcp_internal.h
@@ -49,4 +49,33 @@ bool cbm_mcp_auto_index_within_file_limit(const char *root_path, int file_limit,
 bool cbm_detect_node_in_hunks(const cbm_node_t *node, const cbm_changed_hunk_t *hunks,
                               int hunk_count, const char *file);
 
+#ifdef CBM_ENABLE_TEST_SEAMS
+/* Reject opening one changed file while detect_changes fingerprints its live
+ * snapshot. This makes otherwise platform-specific permission/read races
+ * deterministic without changing production filesystem behavior. */
+typedef bool (*cbm_mcp_snapshot_read_test_hook_fn)(void *context, const char *absolute_path);
+void cbm_mcp_server_set_snapshot_read_test_hook(cbm_mcp_server_t *srv,
+                                                cbm_mcp_snapshot_read_test_hook_fn hook,
+                                                void *context);
+
+/* Filesystem PATH_MAX prevents a portable end-to-end fixture for multi-KiB
+ * stored paths. This seam drives the normal search result ownership,
+ * directory aggregation, and renderer pipeline with synthetic identities. */
+char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
+                                             const char *const *file_paths, int row_count,
+                                             bool json_format);
+
+/* Drive the production raw-source slicer and renderer without relying on an
+ * external grep/PowerShell text decoder. This keeps malformed-byte paging
+ * deterministic on every test platform. */
+char *cbm_mcp_render_raw_preview_for_testing(const char *content, bool content_offset_set,
+                                             size_t content_offset, bool json_format);
+
+/* Exercise search_graph's semantic continuation metadata without allocating
+ * a 100k-row vector fixture. The production emitters remain the code under
+ * test; this seam only supplies their already-ranked page descriptor. */
+char *cbm_mcp_render_semantic_paging_for_testing(int total, int offset, int returned, int limit,
+                                                 bool total_exact, bool json_format);
+#endif
+
 #endif
diff --git a/src/pipeline/pipeline.c b/src/pipeline/pipeline.c
index a5b2647fc..bfbfe5783 100644
--- a/src/pipeline/pipeline.c
+++ b/src/pipeline/pipeline.c
@@ -1766,6 +1766,16 @@ int cbm_pipeline_publish_staged(char *stage_path, const cbm_pipeline_generation_
     }
     cbm_log_info("publish.timing", "block", "fts", "elapsed_ms", itoa_buf((int)elapsed_ms(t_pub)));
     cbm_clock_gettime(CLOCK_MONOTONIC, &t_pub);
+    /* This is the shared commit tail for complete rebuilds and isolated
+     * deltas. Stamp only after every graph/metadata/FTS mutation: a fresh
+     * staging file receives a new uid, while a cloned delta keeps its uid and
+     * advances the mutation counter. A failure discards the private stage. */
+    if (ok && cbm_store_generation_advance(store) != CBM_STORE_OK) {
+        ok = false;
+    }
+    cbm_log_info("publish.timing", "block", "generation", "elapsed_ms",
+                 itoa_buf((int)elapsed_ms(t_pub)));
+    cbm_clock_gettime(CLOCK_MONOTONIC, &t_pub);
     if (ok && !cbm_store_check_integrity(store)) {
         ok = false;
     }
diff --git a/src/store/store.c b/src/store/store.c
index d91346e67..760bda9d5 100644
--- a/src/store/store.c
+++ b/src/store/store.c
@@ -8,6 +8,7 @@
 
 // for ISO timestamp
 
+#include <limits.h>
 #include <stdint.h>
 #include "foundation/constants.h"
 #include "foundation/hash_table.h"
@@ -1597,13 +1598,214 @@ int cbm_store_dump_to_file(cbm_store_t *s, const char *dest_path) {
 
 /* ── Project CRUD ───────────────────────────────────────────────── */
 
+static int rollback_savepoint_preserving_error(cbm_store_t *s, const char *rollback_sql,
+                                               const char *release_sql) {
+    char saved_error[sizeof(s->errbuf)];
+    snprintf(saved_error, sizeof(saved_error), "%s", s->errbuf);
+    (void)sqlite3_exec(s->db, rollback_sql, NULL, NULL, NULL);
+    (void)sqlite3_exec(s->db, release_sql, NULL, NULL, NULL);
+    snprintf(s->errbuf, sizeof(s->errbuf), "%s", saved_error);
+    return CBM_STORE_ERR;
+}
+
+static bool generation_uid_is_canonical(const char *uid) {
+    if (!uid || strlen(uid) != 16) {
+        return false;
+    }
+    for (size_t i = 0; i < 16; i++) {
+        if (!((uid[i] >= '0' && uid[i] <= '9') || (uid[i] >= 'a' && uid[i] <= 'f'))) {
+            return false;
+        }
+    }
+    return true;
+}
+
+static bool generation_counter_parse(const char *text, uint64_t *out) {
+    if (!text || !text[0] || (text[0] == '0' && text[1] != '\0')) {
+        return false;
+    }
+    uint64_t value = 0;
+    for (const unsigned char *p = (const unsigned char *)text; *p; p++) {
+        if (*p < '0' || *p > '9') {
+            return false;
+        }
+        uint64_t digit = (uint64_t)(*p - '0');
+        if (value > (UINT64_MAX - digit) / 10) {
+            return false;
+        }
+        value = value * 10 + digit;
+    }
+    *out = value;
+    return true;
+}
+
+/* Read and validate the two generation keys. Extra store_meta keys belong to
+ * other store features and are deliberately ignored. */
+static int generation_metadata_read(cbm_store_t *s, bool *absent, char uid[17], char counter[21],
+                                    uint64_t *counter_value) {
+    *absent = false;
+    sqlite3_stmt *object = NULL;
+    int rc = sqlite3_prepare_v2(s->db,
+                                "SELECT type FROM sqlite_schema WHERE name='store_meta' "
+                                "AND type IN ('table','view') LIMIT 1;",
+                                CBM_NOT_FOUND, &object, NULL);
+    if (rc != SQLITE_OK) {
+        store_set_error_sqlite(s, "store generation schema probe prepare");
+        return CBM_STORE_ERR;
+    }
+    rc = sqlite3_step(object);
+    if (rc == SQLITE_DONE) {
+        sqlite3_finalize(object);
+        *absent = true;
+        return CBM_STORE_OK;
+    }
+    if (rc != SQLITE_ROW) {
+        store_set_error_sqlite(s, "store generation schema probe");
+        sqlite3_finalize(object);
+        return CBM_STORE_ERR;
+    }
+    const char *object_type = (const char *)sqlite3_column_text(object, 0);
+    bool is_table = object_type && strcmp(object_type, "table") == 0;
+    sqlite3_finalize(object);
+    if (!is_table) {
+        store_set_error(s, "store generation metadata is not a table");
+        return CBM_STORE_ERR;
+    }
+
+    sqlite3_stmt *stmt = NULL;
+    rc = sqlite3_prepare_v2(s->db,
+                            "SELECT k, v, typeof(v) FROM store_meta "
+                            "WHERE k IN ('db_uid','mutation_gen') ORDER BY k;",
+                            CBM_NOT_FOUND, &stmt, NULL);
+    if (rc != SQLITE_OK) {
+        store_set_error_sqlite(s, "store generation metadata prepare");
+        return CBM_STORE_ERR;
+    }
+    bool have_uid = false;
+    bool have_counter = false;
+    while ((rc = sqlite3_step(stmt)) == SQLITE_ROW) {
+        const char *key = (const char *)sqlite3_column_text(stmt, 0);
+        const char *value = (const char *)sqlite3_column_text(stmt, 1);
+        const char *value_type = (const char *)sqlite3_column_text(stmt, 2);
+        if (!key || !value || !value_type || strcmp(value_type, "text") != 0) {
+            store_set_error(s, "store generation metadata has a non-text value");
+            sqlite3_finalize(stmt);
+            return CBM_STORE_ERR;
+        }
+        if ((size_t)sqlite3_column_bytes(stmt, 0) != strlen(key) ||
+            (size_t)sqlite3_column_bytes(stmt, 1) != strlen(value) ||
+            (size_t)sqlite3_column_bytes(stmt, 2) != strlen(value_type)) {
+            store_set_error(s, "store generation metadata contains an embedded NUL");
+            sqlite3_finalize(stmt);
+            return CBM_STORE_ERR;
+        }
+        if (strcmp(key, "db_uid") == 0 && !have_uid && generation_uid_is_canonical(value)) {
+            snprintf(uid, 17, "%s", value);
+            have_uid = true;
+        } else if (strcmp(key, "mutation_gen") == 0 && !have_counter &&
+                   generation_counter_parse(value, counter_value)) {
+            snprintf(counter, 21, "%s", value);
+            have_counter = true;
+        } else {
+            store_set_error(s, "store generation metadata is malformed");
+            sqlite3_finalize(stmt);
+            return CBM_STORE_ERR;
+        }
+    }
+    if (rc != SQLITE_DONE) {
+        store_set_error_sqlite(s, "store generation metadata scan");
+        sqlite3_finalize(stmt);
+        return CBM_STORE_ERR;
+    }
+    sqlite3_finalize(stmt);
+    if (!have_uid || !have_counter) {
+        store_set_error(s, "store generation metadata is incomplete");
+        return CBM_STORE_ERR;
+    }
+    return CBM_STORE_OK;
+}
+
+int cbm_store_generation_advance(cbm_store_t *s) {
+    static const char savepoint[] = "SAVEPOINT cbm_generation_advance;";
+    static const char rollback[] = "ROLLBACK TO cbm_generation_advance;";
+    static const char release[] = "RELEASE cbm_generation_advance;";
+    if (!s || !s->db) {
+        return CBM_STORE_ERR;
+    }
+    int rc = SQLITE_OK;
+    if (exec_sql(s, savepoint) != CBM_STORE_OK) {
+        return CBM_STORE_ERR;
+    }
+
+    bool absent = false;
+    char uid[17] = {0};
+    char counter[21] = {0};
+    uint64_t counter_value = 0;
+    if (generation_metadata_read(s, &absent, uid, counter, &counter_value) != CBM_STORE_OK) {
+        return rollback_savepoint_preserving_error(s, rollback, release);
+    }
+    if (absent) {
+        if (sqlite3_exec(s->db,
+                         "CREATE TABLE store_meta (k TEXT PRIMARY KEY, v TEXT NOT NULL);"
+                         "INSERT INTO store_meta VALUES"
+                         "('db_uid', lower(hex(randomblob(8))));"
+                         "INSERT INTO store_meta VALUES('mutation_gen','0');",
+                         NULL, NULL, NULL) != SQLITE_OK) {
+            store_set_error_sqlite(s, "store generation metadata create");
+            return rollback_savepoint_preserving_error(s, rollback, release);
+        }
+        if (generation_metadata_read(s, &absent, uid, counter, &counter_value) != CBM_STORE_OK ||
+            absent) {
+            if (absent) {
+                store_set_error(s, "store generation metadata create did not persist");
+            }
+            return rollback_savepoint_preserving_error(s, rollback, release);
+        }
+    }
+    if (counter_value == UINT64_MAX) {
+        store_set_error(s, "store generation mutation counter overflow");
+        return rollback_savepoint_preserving_error(s, rollback, release);
+    }
+
+    char next_counter[21];
+    snprintf(next_counter, sizeof(next_counter), "%llu", (unsigned long long)(counter_value + 1));
+    sqlite3_stmt *update = NULL;
+    if (sqlite3_prepare_v2(s->db, "UPDATE store_meta SET v=?1 WHERE k='mutation_gen' AND v=?2;",
+                           CBM_NOT_FOUND, &update, NULL) != SQLITE_OK) {
+        store_set_error_sqlite(s, "store generation advance prepare");
+        return rollback_savepoint_preserving_error(s, rollback, release);
+    }
+    bind_text(update, SKIP_ONE, next_counter);
+    bind_text(update, ST_COL_2, counter);
+    rc = sqlite3_step(update);
+    sqlite3_finalize(update);
+    if (rc != SQLITE_DONE || sqlite3_changes(s->db) != 1) {
+        if (rc != SQLITE_DONE) {
+            store_set_error_sqlite(s, "store generation advance");
+        } else {
+            store_set_error(s, "store generation advance changed an unexpected row count");
+        }
+        return rollback_savepoint_preserving_error(s, rollback, release);
+    }
+    if (exec_sql(s, release) != CBM_STORE_OK) {
+        return rollback_savepoint_preserving_error(s, rollback, release);
+    }
+    return CBM_STORE_OK;
+}
+
 int cbm_store_upsert_project(cbm_store_t *s, const char *name, const char *root_path) {
+    static const char savepoint[] = "SAVEPOINT cbm_upsert_project;";
+    static const char rollback[] = "ROLLBACK TO cbm_upsert_project;";
+    static const char release[] = "RELEASE cbm_upsert_project;";
+    if (!s || !s->db || exec_sql(s, savepoint) != CBM_STORE_OK) {
+        return CBM_STORE_ERR;
+    }
     sqlite3_stmt *stmt =
         prepare_cached(s, &s->stmt_upsert_project,
                        "INSERT INTO projects (name, indexed_at, root_path) VALUES (?1, ?2, ?3) "
                        "ON CONFLICT(name) DO UPDATE SET indexed_at=?2, root_path=?3;");
     if (!stmt) {
-        return CBM_STORE_ERR;
+        return rollback_savepoint_preserving_error(s, rollback, release);
     }
 
     char ts[CBM_SZ_64];
@@ -1616,53 +1818,42 @@ int cbm_store_upsert_project(cbm_store_t *s, const char *name, const char *root_
     int rc = sqlite3_step(stmt);
     if (rc != SQLITE_DONE) {
         store_set_error_sqlite(s, "upsert_project");
-        return CBM_STORE_ERR;
+        sqlite3_reset(stmt);
+        return rollback_savepoint_preserving_error(s, rollback, release);
     }
+    sqlite3_reset(stmt);
 
-    /* Store generation for cursor staleness (pagination): db_uid is a random
-     * identity minted once per DB FILE (a full reindex publishes a fresh file
-     * via the writer, which carries no store_meta — the first upsert_project
-     * on the opened store seeds a NEW uid, so cursors minted against the old
-     * file can never validate against the rebuilt one, whose node ids all
-     * differ). mutation_gen increments on every project upsert — the choke
-     * point every index run (full, incremental, watcher) passes through.
-     * Created here rather than in the byte-level writer: adding a table to
-     * its hand-built sqlite_master is rootpage surgery for zero benefit. */
-    (void)sqlite3_exec(s->db,
-                       "CREATE TABLE IF NOT EXISTS store_meta (k TEXT PRIMARY KEY, v TEXT);"
-                       "INSERT OR IGNORE INTO store_meta VALUES"
-                       "('db_uid', lower(hex(randomblob(8))));"
-                       "INSERT OR IGNORE INTO store_meta VALUES('mutation_gen','0');"
-                       "UPDATE store_meta SET v = CAST(CAST(v AS INTEGER)+1 AS TEXT) "
-                       "WHERE k='mutation_gen';",
-                       NULL, NULL, NULL);
+    if (cbm_store_generation_advance(s) != CBM_STORE_OK) {
+        return rollback_savepoint_preserving_error(s, rollback, release);
+    }
+    if (exec_sql(s, release) != CBM_STORE_OK) {
+        return rollback_savepoint_preserving_error(s, rollback, release);
+    }
     return CBM_STORE_OK;
 }
 
 /* Opaque store generation for pagination cursors: "u<db_uid>g<mutation_gen>",
- * or "legacy" when the DB predates store_meta (read-only opens never create
- * it). A cursor whose embedded generation mismatches the store's current one
- * is stale — the graph may have changed under it. */
+ * or "legacy" only when the DB genuinely predates store_meta. */
 int cbm_store_generation(cbm_store_t *s, char *buf, size_t bufsz) {
     if (!s || !s->db || !buf || bufsz == 0) {
         return CBM_STORE_ERR;
     }
-    snprintf(buf, bufsz, "legacy");
-    sqlite3_stmt *stmt = NULL;
-    if (sqlite3_prepare_v2(s->db,
-                           "SELECT (SELECT v FROM store_meta WHERE k='db_uid'),"
-                           "       (SELECT v FROM store_meta WHERE k='mutation_gen');",
-                           CBM_NOT_FOUND, &stmt, NULL) != SQLITE_OK) {
-        return CBM_STORE_OK; /* pre-migration DB: stable "legacy" generation */
+    bool absent = false;
+    char uid[17] = {0};
+    char counter[21] = {0};
+    uint64_t counter_value = 0;
+    if (generation_metadata_read(s, &absent, uid, counter, &counter_value) != CBM_STORE_OK) {
+        buf[0] = '\0';
+        return CBM_STORE_ERR;
     }
-    if (sqlite3_step(stmt) == SQLITE_ROW) {
-        const char *uid = (const char *)sqlite3_column_text(stmt, 0);
-        const char *gen = (const char *)sqlite3_column_text(stmt, SKIP_ONE);
-        if (uid && gen) {
-            snprintf(buf, bufsz, "u%sg%s", uid, gen);
-        }
+    (void)counter_value;
+    int written =
+        absent ? snprintf(buf, bufsz, "legacy") : snprintf(buf, bufsz, "u%sg%s", uid, counter);
+    if (written < 0 || (size_t)written >= bufsz) {
+        buf[0] = '\0';
+        store_set_error(s, "store generation output buffer is too small");
+        return CBM_STORE_ERR;
     }
-    sqlite3_finalize(stmt);
     return CBM_STORE_OK;
 }
 
@@ -3362,8 +3553,18 @@ int cbm_store_list_files(cbm_store_t *s, const char *project, char ***out, int *
         return CBM_STORE_ERR;
     }
 
+    /* A node path can name a graph-only identity such as a Folder,
+     * <python-builtins>, or another synthetic source. Published indexes have
+     * one canonical File node per scannable path, so prefer that exact set.
+     * Legacy/manual stores without File nodes retain their previous node-path
+     * fallback (minus Folder directories). Missing canonical paths stay in
+     * the list so search_code still fails closed on a stale snapshot. */
     const char *sql = "SELECT DISTINCT file_path FROM nodes "
-                      "WHERE project = ?1 AND file_path IS NOT NULL AND file_path != ''";
+                      "WHERE project = ?1 AND label != 'Folder' "
+                      "AND file_path IS NOT NULL AND file_path != '' "
+                      "AND (label = 'File' OR NOT EXISTS ("
+                      "SELECT 1 FROM nodes WHERE project = ?1 AND label = 'File')) "
+                      "ORDER BY file_path";
     sqlite3_stmt *stmt = NULL;
     if (sqlite3_prepare_v2(s->db, sql, CBM_NOT_FOUND, &stmt, NULL) != SQLITE_OK) {
         return CBM_STORE_ERR;
@@ -4451,10 +4652,14 @@ void cbm_store_search_free(cbm_search_output_t *out) {
 
 static int bfs_collect_edges(cbm_store_t *s, int64_t start_id, const cbm_node_hop_t *visited,
                              int visited_count, const char *types_clause, const char **edge_types,
-                             int edge_type_count, cbm_edge_info_t **out_edges,
-                             int *out_edge_count) {
+                             int edge_type_count, int max_edges, cbm_edge_info_t **out_edges,
+                             int *out_edge_count, bool *out_truncated) {
     *out_edges = NULL;
     *out_edge_count = 0;
+    *out_truncated = false;
+    if (max_edges == 0) {
+        return CBM_STORE_OK;
+    }
 
     /* Visited-ID set via a per-connection TEMP table. The previous approach
      * interpolated the ids into a fixed 4KB SQL string: past ~1000 visited
@@ -4466,22 +4671,37 @@ static int bfs_collect_edges(cbm_store_t *s, int64_t start_id, const cbm_node_ho
                      "CREATE TEMP TABLE IF NOT EXISTS bfs_ids (id INTEGER PRIMARY KEY);"
                      "DELETE FROM bfs_ids;",
                      NULL, NULL, NULL) != SQLITE_OK) {
-        return CBM_STORE_OK; /* best-effort: nodes without edges beat an error */
+        store_set_error_sqlite(s, "bfs edge ids");
+        return CBM_STORE_ERR;
     }
     sqlite3_stmt *ins = NULL;
     if (sqlite3_prepare_v2(s->db, "INSERT OR IGNORE INTO bfs_ids(id) VALUES (?1)", CBM_NOT_FOUND,
                            &ins, NULL) != SQLITE_OK) {
-        return CBM_STORE_OK;
+        store_set_error_sqlite(s, "bfs edge ids prepare");
+        return CBM_STORE_ERR;
     }
     sqlite3_bind_int64(ins, SKIP_ONE, start_id);
-    (void)sqlite3_step(ins);
+    if (sqlite3_step(ins) != SQLITE_DONE) {
+        store_set_error_sqlite(s, "bfs edge root id");
+        sqlite3_finalize(ins);
+        return CBM_STORE_ERR;
+    }
     for (int i = 0; i < visited_count; i++) {
         sqlite3_reset(ins);
         sqlite3_bind_int64(ins, SKIP_ONE, visited[i].node.id);
-        (void)sqlite3_step(ins);
+        if (sqlite3_step(ins) != SQLITE_DONE) {
+            store_set_error_sqlite(s, "bfs edge visited id");
+            sqlite3_finalize(ins);
+            return CBM_STORE_ERR;
+        }
     }
     sqlite3_finalize(ins);
 
+    char limit_clause[ST_BUF_64] = "";
+    if (max_edges > 0) {
+        snprintf(limit_clause, sizeof(limit_clause), " LIMIT %d",
+                 max_edges < INT_MAX ? max_edges + SKIP_ONE : max_edges);
+    }
     char edge_sql[ST_SQL_BUF];
     snprintf(edge_sql, sizeof(edge_sql),
              "SELECT n1.name, n2.name, e.type, e.source_id, e.target_id, e.properties "
@@ -4490,15 +4710,15 @@ static int bfs_collect_edges(cbm_store_t *s, int64_t start_id, const cbm_node_ho
              "JOIN nodes n2 ON n2.id = e.target_id "
              "WHERE e.source_id IN (SELECT id FROM bfs_ids) "
              "AND e.target_id IN (SELECT id FROM bfs_ids) "
-             "AND e.type IN (%s)",
-             types_clause);
+             "AND e.type IN (%s) "
+             "ORDER BY e.source_id, e.target_id, e.type%s",
+             types_clause, limit_clause);
 
     sqlite3_stmt *estmt = NULL;
     int rc = sqlite3_prepare_v2(s->db, edge_sql, CBM_NOT_FOUND, &estmt, NULL);
     if (rc != SQLITE_OK) {
-        *out_edges = NULL;
-        *out_edge_count = 0;
-        return CBM_STORE_OK;
+        store_set_error_sqlite(s, "bfs edges prepare");
+        return CBM_STORE_ERR;
     }
 
     if (edge_type_count > 0) {
@@ -4537,6 +4757,15 @@ static int bfs_collect_edges(cbm_store_t *s, int64_t start_id, const cbm_node_ho
     }
     sqlite3_finalize(estmt);
 
+    if (max_edges > 0 && en > max_edges) {
+        en = max_edges;
+        safe_str_free(&edges[en].from_name);
+        safe_str_free(&edges[en].to_name);
+        safe_str_free(&edges[en].type);
+        safe_str_free(&edges[en].properties_json);
+        *out_truncated = true;
+    }
+
     *out_edges = edges;
     *out_edge_count = en;
     return CBM_STORE_OK;
@@ -4563,9 +4792,13 @@ static void bfs_build_types_clause(int edge_type_count, char *buf, int buf_sz) {
     }
 }
 
-int cbm_store_bfs(cbm_store_t *s, int64_t start_id, const char *direction, const char **edge_types,
-                  int edge_type_count, int max_depth, int max_results, cbm_traverse_result_t *out) {
+int cbm_store_bfs_with_edge_limit(cbm_store_t *s, int64_t start_id, const char *direction,
+                                  const char **edge_types, int edge_type_count, int max_depth,
+                                  int max_results, int max_edges, cbm_traverse_result_t *out) {
     memset(out, 0, sizeof(*out));
+    if (max_results < 0) {
+        max_results = 0;
+    }
 
     cbm_node_t root = {0};
     int rc = cbm_store_find_node_by_id(s, start_id, &root);
@@ -4616,7 +4849,8 @@ int cbm_store_bfs(cbm_store_t *s, int64_t start_id, const char *direction, const
               * watermarks and reproducible trace output depend on it. */
              "ORDER BY hop, n.id "
              "LIMIT %d;",
-             (long long)start_id, next_id, join_cond, types_clause, max_depth, max_results);
+             (long long)start_id, next_id, join_cond, types_clause, max_depth,
+             max_results < INT_MAX ? max_results + SKIP_ONE : max_results);
 
     sqlite3_stmt *stmt = NULL;
     rc = sqlite3_prepare_v2(s->db, sql, CBM_NOT_FOUND, &stmt, NULL);
@@ -4658,13 +4892,25 @@ int cbm_store_bfs(cbm_store_t *s, int64_t start_id, const char *direction, const
 
     sqlite3_finalize(stmt);
 
+    if (n > max_results) {
+        n = max_results;
+        cbm_node_free_fields(&visited[n].node);
+        out->truncated = true;
+    }
+
     out->visited = visited;
     out->visited_count = n;
 
-    /* Collect edges between visited nodes (including root) */
-    if (n > 0) {
-        bfs_collect_edges(s, start_id, out->visited, n, types_clause, edge_types, edge_type_count,
-                          &out->edges, &out->edge_count);
+    /* Edge properties are a secondary, potentially dense all-pairs lookup.
+     * Lean callers pass max_edges=0 and avoid it entirely; diagnostics callers
+     * pass an explicit ceiling and receive an honest saturation bit. */
+    if (n > 0 && max_edges != 0) {
+        rc = bfs_collect_edges(s, start_id, out->visited, n, types_clause, edge_types,
+                               edge_type_count, max_edges, &out->edges, &out->edge_count,
+                               &out->edges_truncated);
+        if (rc != CBM_STORE_OK) {
+            return rc;
+        }
     } else {
         out->edges = NULL;
         out->edge_count = 0;
@@ -4673,6 +4919,15 @@ int cbm_store_bfs(cbm_store_t *s, int64_t start_id, const char *direction, const
     return CBM_STORE_OK;
 }
 
+int cbm_store_bfs(cbm_store_t *s, int64_t start_id, const char *direction, const char **edge_types,
+                  int edge_type_count, int max_depth, int max_results, cbm_traverse_result_t *out) {
+    /* Compatibility API: existing store/Cypher consumers historically
+     * requested the complete internal edge set. MCP trace calls use the
+     * explicit bounded API above. */
+    return cbm_store_bfs_with_edge_limit(s, start_id, direction, edge_types, edge_type_count,
+                                         max_depth, max_results, -1, out);
+}
+
 /* Multi-source BFS: one recursive CTE anchored on ALL seeds (via a temp
  * table — never a per-seed loop, which re-walks overlapping hub subgraphs
  * seed_count times). Semantics for impact analysis:
@@ -8449,6 +8704,18 @@ static cbm_vector_result_t *vs_append_result(cbm_vector_result_t *results, int *
     return results;
 }
 
+static int vs_ranked_result_cmp(const void *lhs, const void *rhs) {
+    const cbm_vector_result_t *a = lhs;
+    const cbm_vector_result_t *b = rhs;
+    if (a->score > b->score) {
+        return -1;
+    }
+    if (a->score < b->score) {
+        return 1;
+    }
+    return (a->node_id > b->node_id) - (a->node_id < b->node_id);
+}
+
 int cbm_store_vector_search(cbm_store_t *s, const char *project, const char **keywords,
                             int keyword_count, int limit, cbm_vector_result_t **out,
                             int *out_count) {
@@ -8464,16 +8731,15 @@ int cbm_store_vector_search(cbm_store_t *s, const char *project, const char **ke
         return CBM_STORE_OK;
     }
 
-    /* Scan all node vectors, compute per-keyword cosine, take min.
-     * We use the FIRST keyword as the SQL sort (for top-K pre-filter),
-     * then re-score with min across all keywords in the append helper. */
+    /* Use the first keyword for a cheap candidate ordering, then score each
+     * materialized candidate by min-cosine across every keyword. */
     const char *sql = "SELECT n.id, n.name, n.qualified_name, n.file_path, n.label,"
                       "       cbm_cosine_i8(v.vector, ?1) as score, v.vector"
                       " FROM node_vectors v"
                       " INNER JOIN nodes n ON n.id = v.node_id"
                       " WHERE v.project = ?2"
                       " AND n.label IN (" CBM_SQL_CALLABLE_OR_TYPE_LABELS ")"
-                      " ORDER BY score DESC"
+                      " ORDER BY score DESC, n.id ASC"
                       " LIMIT ?3";
 
     sqlite3_stmt *stmt = NULL;
@@ -8483,59 +8749,74 @@ int cbm_store_vector_search(cbm_store_t *s, const char *project, const char **ke
         return CBM_STORE_ERR;
     }
 
-    /* Use first keyword for SQL pre-filter, fetch more candidates for re-ranking */
-    int fetch_limit = (limit > 0 ? limit : CBM_SZ_16) * ST_COL_5;
+    /* A fixed 5x prefilter is normally ample, but it is not a proof: a later
+     * candidate can have a lower first-keyword score and a much higher
+     * all-keyword min-score. Expand until either the scan is exhausted or the
+     * Kth final score is strictly above the best possible omitted score. This
+     * makes top-K prefixes identical for every requested K, which semantic
+     * offset pagination requires. */
+    int requested_limit = limit > 0 ? limit : CBM_SZ_16;
+    int fetch_limit = requested_limit > INT_MAX / ST_COL_5 ? INT_MAX : requested_limit * ST_COL_5;
     sqlite3_bind_blob(stmt, SKIP_ONE, kw_vecs[0], VS_VEC_DIM, SQLITE_STATIC);
     sqlite3_bind_text(stmt, ST_COL_2, project, SQLITE_AUTO_LEN, SQLITE_STATIC);
-    sqlite3_bind_int(stmt, ST_COL_3, fetch_limit);
-
-    {
-        char kw_buf[VS_STR_BUF];
-        char fl_buf[VS_STR_BUF];
-        snprintf(kw_buf, sizeof(kw_buf), "%d", actual_kw);
-        snprintf(fl_buf, sizeof(fl_buf), "%d", fetch_limit);
-        cbm_log_info("vector_search.exec", "kw_count", kw_buf, "fetch_limit", fl_buf, "project",
-                     project);
-    }
 
     cbm_vector_result_t *results = NULL;
     int count = 0;
-    int cap = 0;
-    int step_rc = 0;
-    while ((step_rc = sqlite3_step(stmt)) == SQLITE_ROW) {
-        cbm_vector_result_t *grown =
-            vs_append_result(results, &count, &cap, stmt, kw_vecs, actual_kw);
-        if (!grown) {
+    for (;;) {
+        int cap = 0;
+        int step_rc;
+        double omitted_score_ceiling = 0.0;
+        sqlite3_bind_int(stmt, ST_COL_3, fetch_limit);
+        while ((step_rc = sqlite3_step(stmt)) == SQLITE_ROW) {
+            omitted_score_ceiling = sqlite3_column_double(stmt, ST_COL_5);
+            cbm_vector_result_t *grown =
+                vs_append_result(results, &count, &cap, stmt, kw_vecs, actual_kw);
+            if (!grown) {
+                step_rc = SQLITE_NOMEM;
+                break;
+            }
+            results = grown;
+        }
+        if (step_rc != SQLITE_DONE) {
+            char rc_buf[VS_STR_BUF];
+            snprintf(rc_buf, sizeof(rc_buf), "%d", step_rc);
+            cbm_log_warn("vector_search.step_error", "rc", rc_buf, "msg", sqlite3_errmsg(s->db));
+            cbm_store_free_vector_results(results, count);
+            sqlite3_finalize(stmt);
+            return CBM_STORE_ERR;
+        }
+
+        if (count > 1) {
+            qsort(results, (size_t)count, sizeof(*results), vs_ranked_result_cmp);
+        }
+        bool scan_exhausted = count < fetch_limit;
+        bool top_k_certified = scan_exhausted || count < requested_limit ||
+                               results[requested_limit - 1].score > omitted_score_ceiling;
+        if (top_k_certified || fetch_limit == INT_MAX) {
             break;
         }
-        results = grown;
-    }
 
-    if (step_rc != SQLITE_DONE) {
-        char rc_buf[VS_STR_BUF];
-        snprintf(rc_buf, sizeof(rc_buf), "%d", step_rc);
-        cbm_log_warn("vector_search.step_error", "rc", rc_buf, "msg", sqlite3_errmsg(s->db));
+        cbm_store_free_vector_results(results, count);
+        results = NULL;
+        count = 0;
+        fetch_limit = fetch_limit > INT_MAX / ST_COL_2 ? INT_MAX : fetch_limit * ST_COL_2;
+        sqlite3_reset(stmt);
     }
+
     {
+        char kw_buf[VS_STR_BUF];
+        char fl_buf[VS_STR_BUF];
         char cnt_buf[VS_STR_BUF];
+        snprintf(kw_buf, sizeof(kw_buf), "%d", actual_kw);
+        snprintf(fl_buf, sizeof(fl_buf), "%d", fetch_limit);
         snprintf(cnt_buf, sizeof(cnt_buf), "%d", count);
-        cbm_log_info("vector_search.done", "candidates", cnt_buf);
+        cbm_log_info("vector_search.done", "kw_count", kw_buf, "fetch_limit", fl_buf, "candidates",
+                     cnt_buf);
     }
     sqlite3_finalize(stmt);
 
-    /* Re-sort by min-score (SQL sorted by first keyword only) */
-    for (int i = 0; i < count - SKIP_ONE; i++) {
-        for (int j = i + SKIP_ONE; j < count; j++) {
-            if (results[j].score > results[i].score) {
-                cbm_vector_result_t tmp = results[i];
-                results[i] = results[j];
-                results[j] = tmp;
-            }
-        }
-    }
-
     /* Trim to requested limit */
-    int final_limit = limit > 0 ? limit : CBM_SZ_16;
+    int final_limit = requested_limit;
     if (count > final_limit) {
         for (int i = final_limit; i < count; i++) {
             free(results[i].name);
diff --git a/src/store/store.h b/src/store/store.h
index 65f4971f8..89f5c436f 100644
--- a/src/store/store.h
+++ b/src/store/store.h
@@ -88,8 +88,8 @@ int cbm_store_find_nodes_by_qn_suffix(cbm_store_t *s, const char *project, const
 /* Get CALLS degree of a node (inbound and outbound). */
 void cbm_store_node_degree(cbm_store_t *s, int64_t node_id, int *in_deg, int *out_deg);
 
-/* Get distinct file paths for a project. Caller must free each out[i] and out itself.
- * Returns CBM_STORE_OK or CBM_STORE_ERR. */
+/* Get distinct canonical File-node paths, with a non-Folder node fallback for legacy/manual
+ * stores that have no File nodes. Caller frees each out[i] and out itself. */
 int cbm_store_list_files(cbm_store_t *s, const char *project, char ***out, int *count);
 
 /* Get caller/callee names for a node (CALLS/HTTP_CALLS/ASYNC_CALLS edges).
@@ -211,6 +211,8 @@ typedef struct {
     int visited_count;
     cbm_edge_info_t *edges;
     int edge_count;
+    bool truncated;       /* traversal safety ceiling reached; counts are lower bounds */
+    bool edges_truncated; /* optional edge-data ceiling reached; node counts stay exact */
 } cbm_traverse_result_t;
 
 /* ── Schema introspection ───────────────────────────────────────── */
@@ -351,9 +353,17 @@ int cbm_store_checkpoint(cbm_store_t *s);
  * connection, in bytes; -1 = unlimited (SQLite default / pre-fix). */
 int64_t cbm_store_journal_size_limit(cbm_store_t *s);
 
+/* Advance the pagination-cursor generation atomically. Seeds a genuinely
+ * legacy database with a fresh per-file uid, preserves that uid thereafter,
+ * and increments its canonical uint64 mutation counter. Safe inside an
+ * existing transaction (implemented with a nested savepoint); malformed or
+ * partial metadata fails closed without committing a partial advance. */
+int cbm_store_generation_advance(cbm_store_t *s);
+
 /* Opaque store generation for pagination-cursor staleness detection:
- * "u<db_uid>g<mutation_gen>" — db_uid is minted per DB file, mutation_gen
- * bumps on every index run. "legacy" for DBs predating store_meta. */
+ * "u<16-lower-hex-db_uid>g<canonical-uint64-mutation_gen>". Returns "legacy"
+ * only when store_meta is genuinely absent; malformed or missing metadata is
+ * an error. */
 int cbm_store_generation(cbm_store_t *s, char *buf, size_t bufsz);
 
 /* Seal a fully-written staging database before atomic publication.
@@ -600,6 +610,14 @@ void cbm_store_search_free(cbm_search_output_t *out);
 int cbm_store_bfs(cbm_store_t *s, int64_t start_id, const char *direction, const char **edge_types,
                   int edge_type_count, int max_depth, int max_results, cbm_traverse_result_t *out);
 
+/* BFS with an explicit edge-data budget. max_edges=0 skips the secondary
+ * all-pairs edge lookup; max_edges>0 collects at most that many edges and
+ * raises out->edges_truncated on saturation. Node traversal is unchanged.
+ * This is intended for lean callers that need nodes but not edge properties. */
+int cbm_store_bfs_with_edge_limit(cbm_store_t *s, int64_t start_id, const char *direction,
+                                  const char **edge_types, int edge_type_count, int max_depth,
+                                  int max_results, int max_edges, cbm_traverse_result_t *out);
+
 /* Multi-source BFS from ALL seed ids at once (one CTE, temp-table anchored).
  * Seeds are EXCLUDED from the result (impact semantics); MIN(hop) across the
  * seed set; canonical (hop,id) order; *truncated set when the max_results
diff --git a/src/ui/http_server.c b/src/ui/http_server.c
index 066eafe42..5e2154048 100644
--- a/src/ui/http_server.c
+++ b/src/ui/http_server.c
@@ -1647,7 +1647,8 @@ static bool rpc_is_allowed_for_ui(const char *body, size_t body_len) {
     const char *name_text = yyjson_is_str(name) ? yyjson_get_str(name) : NULL;
     bool allowed =
         method_text && strcmp(method_text, "tools/call") == 0 && name_text &&
-        (strcmp(name_text, "list_projects") == 0 || strcmp(name_text, "get_code_snippet") == 0);
+        (strcmp(name_text, "list_projects") == 0 || strcmp(name_text, "get_graph_schema") == 0 ||
+         strcmp(name_text, "get_code_snippet") == 0);
     yyjson_doc_free(document);
     return allowed;
 }
diff --git a/tests/scale_contract.sh b/tests/scale_contract.sh
index 5798f91d5..e1458d49d 100644
--- a/tests/scale_contract.sh
+++ b/tests/scale_contract.sh
@@ -45,11 +45,10 @@ project_name() { printf '%s' "$1" | sed 's#^/##; s#[^A-Za-z0-9._-]#-#g'; }
 # Run query_graph and print the first integer in the JSON response (or -1).
 query_count() {
     local proj="$1" cypher="$2" resp
-    resp="$("$BIN" cli query_graph "{\"project\":\"$proj\",\"query\":\"$cypher\"}" 2>/dev/null)"
-    printf '%s' "$resp" | "$PY" -c 'import sys,re
-s=sys.stdin.read()
-m=re.findall(r"-?\d+", s)
-print(m[0] if m else -1)' 2>/dev/null || echo -1
+    resp="$("$BIN" cli query_graph "{\"project\":\"$proj\",\"query\":\"$cypher\",\"format\":\"json\"}" 2>/dev/null)"
+    printf '%s' "$resp" | "$PY" -c 'import json,sys
+d=json.load(sys.stdin); rows=d.get("rows", [])
+print(rows[0][0] if rows and rows[0] else -1)' 2>/dev/null || echo -1
 }
 
 assert_lang() {
diff --git a/tests/test_cli.c b/tests/test_cli.c
index 333c3fa25..d56ada449 100644
--- a/tests/test_cli.c
+++ b/tests/test_cli.c
@@ -21,6 +21,7 @@
 #include <daemon/runtime.h>
 #include <daemon/version_cohort.h>
 #include <foundation/constants.h>
+#include <foundation/log.h>
 #include <foundation/platform.h>
 #include <mcp/mcp.h>
 #include <foundation/yaml.h>
@@ -53,10 +54,138 @@ void cbm_cli_set_activation_cleanup_failure_for_test(bool enabled);
 int cbm_cli_activation_abort_cleanup_probe_for_test(void);
 bool cbm_cli_activation_test_ops_installed(void);
 
+/* CLI config lifecycle tests exercise the real activation guard on POSIX. Keep
+ * that protocol coverage, but bind it to this suite's private endpoint so an
+ * editor using the developer's installed CBM cannot make an unrelated cleanup
+ * assertion fail. One focused activation-order test temporarily overrides this
+ * parent and restores it before the remaining suite continues. */
+static char g_cli_suite_runtime_parent[512];
+
+TEST(cli_suite_uses_private_activation_runtime) {
+    const char *runtime_parent = cbm_cli_activation_runtime_parent_for_test();
+    ASSERT_NOT_NULL(runtime_parent);
+    ASSERT_STR_EQ(runtime_parent, g_cli_suite_runtime_parent);
+    PASS();
+}
+
 TEST(cli_progress_visibility_policy) {
-    ASSERT_TRUE(cbm_cli_progress_enabled(true, false));
-    ASSERT_TRUE(cbm_cli_progress_enabled(false, true));
-    ASSERT_FALSE(cbm_cli_progress_enabled(false, false));
+    ASSERT_TRUE(cbm_cli_progress_enabled(true, false, false));
+    ASSERT_TRUE(cbm_cli_progress_enabled(false, false, true));
+    ASSERT_FALSE(cbm_cli_progress_enabled(false, false, false));
+    ASSERT_FALSE(cbm_cli_progress_enabled(false, true, true));
+    ASSERT_FALSE(cbm_cli_progress_enabled(true, true, true));
+    PASS();
+}
+
+TEST(cli_quiet_is_stripped_before_tool_argument_forwarding) {
+    char *argv[] = {"search_graph", "--project", "demo", "--quiet"};
+    int argc = (int)(sizeof(argv) / sizeof(argv[0]));
+    cbm_cli_output_flags_t flags;
+    char error[256] = {0};
+
+    ASSERT_TRUE(cbm_cli_output_flags_parse(&argc, argv, &flags, error, sizeof(error)));
+    ASSERT_TRUE(flags.quiet_requested);
+    ASSERT_FALSE(flags.progress_requested);
+    ASSERT_FALSE(flags.verbose_requested);
+    ASSERT_EQ(argc, 3);
+    ASSERT_STR_EQ(argv[0], "search_graph");
+    ASSERT_STR_EQ(argv[1], "--project");
+    ASSERT_STR_EQ(argv[2], "demo");
+
+    char *build_error = NULL;
+    char *json = cbm_cli_build_args_json(argv[0], argc - 1, argv + 1, &build_error);
+    ASSERT_NOT_NULL(json);
+    ASSERT_NULL(build_error);
+    ASSERT_NOT_NULL(strstr(json, "\"project\":\"demo\""));
+    ASSERT_NULL(strstr(json, "quiet"));
+    free(json);
+    PASS();
+}
+
+TEST(cli_quiet_rejects_other_outer_output_modes_with_guidance) {
+    char *progress_argv[] = {"--quiet", "--progress", "search_graph"};
+    int progress_argc = (int)(sizeof(progress_argv) / sizeof(progress_argv[0]));
+    cbm_cli_output_flags_t progress_flags;
+    char progress_error[256] = {0};
+    ASSERT_FALSE(cbm_cli_output_flags_parse(&progress_argc, progress_argv, &progress_flags,
+                                            progress_error, sizeof(progress_error)));
+    ASSERT_NOT_NULL(strstr(progress_error, "--quiet"));
+    ASSERT_NOT_NULL(strstr(progress_error, "--progress"));
+    ASSERT_NOT_NULL(strstr(progress_error, "errors-only"));
+
+    char *verbose_argv[] = {"--quiet", "--verbose", "index_status"};
+    int verbose_argc = (int)(sizeof(verbose_argv) / sizeof(verbose_argv[0]));
+    cbm_cli_output_flags_t verbose_flags;
+    char verbose_error[256] = {0};
+    ASSERT_FALSE(cbm_cli_output_flags_parse(&verbose_argc, verbose_argv, &verbose_flags,
+                                            verbose_error, sizeof(verbose_error)));
+    ASSERT_NOT_NULL(strstr(verbose_error, "--verbose"));
+    ASSERT_NOT_NULL(strstr(verbose_error, "informational diagnostics"));
+
+    /* Existing progress plus verbose behavior remains valid; only quiet is
+     * exclusive with the two output-expanding controls. */
+    char *compatible_argv[] = {"--progress", "--verbose", "search_graph"};
+    int compatible_argc = (int)(sizeof(compatible_argv) / sizeof(compatible_argv[0]));
+    cbm_cli_output_flags_t compatible_flags;
+    char compatible_error[256] = {0};
+    ASSERT_TRUE(cbm_cli_output_flags_parse(&compatible_argc, compatible_argv, &compatible_flags,
+                                           compatible_error, sizeof(compatible_error)));
+    ASSERT_TRUE(compatible_flags.progress_requested);
+    ASSERT_TRUE(compatible_flags.verbose_requested);
+    ASSERT_FALSE(compatible_flags.quiet_requested);
+    ASSERT_EQ(compatible_argc, 1);
+    ASSERT_STR_EQ(compatible_argv[0], "search_graph");
+    PASS();
+}
+
+TEST(cli_quiet_preserves_tool_level_verbose_argument) {
+    char *argv[] = {"--quiet", "index_status", "--verbose"};
+    int argc = (int)(sizeof(argv) / sizeof(argv[0]));
+    cbm_cli_output_flags_t flags;
+    char error[256] = {0};
+
+    ASSERT_TRUE(cbm_cli_output_flags_parse(&argc, argv, &flags, error, sizeof(error)));
+    ASSERT_TRUE(flags.quiet_requested);
+    ASSERT_FALSE(flags.verbose_requested);
+    ASSERT_EQ(argc, 2);
+    ASSERT_STR_EQ(argv[0], "index_status");
+    ASSERT_STR_EQ(argv[1], "--verbose");
+    PASS();
+}
+
+static FILE *s_cli_quiet_log_capture;
+
+static void cli_quiet_log_capture(const char *line) {
+    if (s_cli_quiet_log_capture && line) {
+        (void)fprintf(s_cli_quiet_log_capture, "%s\n", line);
+    }
+}
+
+TEST(cli_quiet_suppresses_ordinary_diagnostics_but_preserves_errors) {
+    FILE *out = tmpfile();
+    ASSERT_NOT_NULL(out);
+    CBMLogLevel previous_level = cbm_log_get_level();
+    CBMLogFormat previous_format = cbm_log_get_format();
+    cbm_log_set_level(CBM_LOG_DEBUG);
+    cbm_log_set_format(CBM_LOG_FORMAT_TEXT);
+    s_cli_quiet_log_capture = out;
+    cbm_log_set_sink(cli_quiet_log_capture);
+
+    cbm_cli_diagnostics_configure(true, false);
+    cbm_log_info("quiet.info", "detail", "drop");
+    cbm_log_warn("quiet.warning", "detail", "drop");
+    cbm_log_error("quiet.error", "detail", "keep");
+
+    cbm_log_set_sink(NULL);
+    s_cli_quiet_log_capture = NULL;
+    cbm_log_set_level(previous_level);
+    cbm_log_set_format(previous_format);
+    ASSERT_EQ(fseek(out, 0, SEEK_SET), 0);
+    char rendered[512] = {0};
+    size_t rendered_size = fread(rendered, 1, sizeof(rendered) - 1, out);
+    (void)fclose(out);
+    ASSERT_TRUE(rendered_size > 0);
+    ASSERT_STR_EQ(rendered, "level=error msg=quiet.error detail=keep\n");
     PASS();
 }
 
@@ -99,6 +228,75 @@ TEST(cli_progress_sink_accepts_worker_json_logs) {
     PASS();
 }
 
+TEST(cli_progress_sink_enables_lifecycle_info_then_restores_quiet_default) {
+    FILE *out = tmpfile();
+    ASSERT_NOT_NULL(out);
+    cbm_log_set_level(CBM_LOG_WARN);
+
+    cbm_progress_sink_init(out);
+    ASSERT_EQ(cbm_log_get_level(), CBM_LOG_INFO);
+    cbm_log_info("pipeline.discover", "files", "3");
+    cbm_progress_sink_fini();
+    ASSERT_EQ(cbm_log_get_level(), CBM_LOG_WARN);
+
+    ASSERT_EQ(fseek(out, 0, SEEK_SET), 0);
+    char rendered[256] = {0};
+    size_t rendered_size = fread(rendered, 1, sizeof(rendered) - 1, out);
+    (void)fclose(out);
+    ASSERT_TRUE(rendered_size > 0);
+    ASSERT_NOT_NULL(strstr(rendered, "Discovering files (3 found)"));
+    PASS();
+}
+
+TEST(cli_progress_sink_suppresses_noise_and_preserves_failures) {
+    FILE *out = tmpfile();
+    ASSERT_NOT_NULL(out);
+
+    cbm_progress_sink_init(out);
+    cbm_progress_sink_fn("level=info msg=parallel.extract.progress done=1 total=2");
+    cbm_progress_sink_fn("level=debug msg=worker.detail value=drop-debug");
+    cbm_progress_sink_fn(
+        "{\"level\":\"info\",\"event\":\"worker.detail\",\"value\":\"drop-info\"}");
+    cbm_progress_sink_fn("level=warn msg=worker.warning detail=keep-text");
+    cbm_progress_sink_fn(
+        "{\"level\":\"error\",\"event\":\"worker.failure\",\"detail\":\"keep-json\"}");
+    cbm_progress_sink_fini();
+
+    ASSERT_EQ(fseek(out, 0, SEEK_SET), 0);
+    char rendered[1024] = {0};
+    size_t rendered_size = fread(rendered, 1, sizeof(rendered) - 1, out);
+    (void)fclose(out);
+
+    ASSERT_TRUE(rendered_size > 0);
+    ASSERT_STR_EQ(rendered,
+                  "\r  Extracting: 1/2 files (50%)\n"
+                  "level=warn msg=worker.warning detail=keep-text\n"
+                  "{\"level\":\"error\",\"event\":\"worker.failure\",\"detail\":\"keep-json\"}\n");
+    PASS();
+}
+
+TEST(cli_progress_sink_preserves_explicit_verbose_diagnostics) {
+    FILE *out = tmpfile();
+    ASSERT_NOT_NULL(out);
+    CBMLogLevel previous_level = cbm_log_get_level();
+    cbm_log_set_level(CBM_LOG_DEBUG);
+
+    cbm_progress_sink_init(out);
+    cbm_log_info("cli.daemon.spawned", "hint", "keep-info");
+    cbm_log_debug("cli.detail", "value", "keep-debug");
+    cbm_progress_sink_fini();
+    cbm_log_set_level(previous_level);
+
+    ASSERT_EQ(fseek(out, 0, SEEK_SET), 0);
+    char rendered[1024] = {0};
+    size_t rendered_size = fread(rendered, 1, sizeof(rendered) - 1, out);
+    (void)fclose(out);
+    ASSERT_TRUE(rendered_size > 0);
+    ASSERT_NOT_NULL(strstr(rendered, "msg=cli.daemon.spawned"));
+    ASSERT_NOT_NULL(strstr(rendered, "msg=cli.detail"));
+    PASS();
+}
+
 enum { CLI_PROGRESS_RACE_THREADS = 4, CLI_PROGRESS_RACE_ROUNDS = 32 };
 
 typedef struct {
@@ -945,7 +1143,7 @@ TEST(cli_activation_quiesce_does_not_wait_on_bootstrap_startup) {
     snprintf(dir_arg, sizeof(dir_arg), "--dir=%s", install_dir);
     char *install_argv[] = {"--force", "--skip-config", "--yes", dir_arg};
     int install_rc = child_ready ? cli_test_cmd_install(4, install_argv) : -1;
-    cbm_cli_set_activation_runtime_parent_for_test(NULL);
+    cbm_cli_set_activation_runtime_parent_for_test(g_cli_suite_runtime_parent);
     cbm_set_auto_answer_for_test(0);
 
     int child_status = 0;
@@ -7817,6 +8015,57 @@ TEST(cli_hook_session_resolves_custom_named_index_by_root_path) {
     PASS();
 }
 
+TEST(cli_hook_session_exhausts_project_registry_pages) {
+    enum { DECOY_DATABASES = 500 };
+    char tmpdir[256];
+    snprintf(tmpdir, sizeof(tmpdir), "/tmp/cli-hook-project-pages-XXXXXX");
+    if (!cbm_mkdtemp(tmpdir))
+        FAIL("cbm_mkdtemp failed");
+    char cache[512];
+    char decoy_root[512];
+    char target_root[512];
+    char decoy_db[640];
+    char target_db[640];
+    snprintf(cache, sizeof(cache), "%s/cache", tmpdir);
+    snprintf(decoy_root, sizeof(decoy_root), "%s/decoy", tmpdir);
+    snprintf(target_root, sizeof(target_root), "%s/target", tmpdir);
+    snprintf(decoy_db, sizeof(decoy_db), "%s/decoy-000.db", cache);
+    snprintf(target_db, sizeof(target_db), "%s/target.db", cache);
+    test_mkdirp(cache);
+    test_mkdirp(decoy_root);
+    test_mkdirp(target_root);
+
+    cbm_store_t *store = cbm_store_open_path(decoy_db);
+    ASSERT_NOT_NULL(store);
+    ASSERT_EQ(cbm_store_upsert_project(store, "aaa-decoy", decoy_root), CBM_STORE_OK);
+    cbm_store_close(store);
+    for (int i = 1; i < DECOY_DATABASES; i++) {
+        char copy[640];
+        snprintf(copy, sizeof(copy), "%s/decoy-%03d.db", cache, i);
+        ASSERT_EQ(cbm_copy_file(decoy_db, copy), 0);
+    }
+
+    store = cbm_store_open_path(target_db);
+    ASSERT_NOT_NULL(store);
+    ASSERT_EQ(cbm_store_upsert_project(store, "zzz-custom-project", target_root), CBM_STORE_OK);
+    cbm_store_close(store);
+
+    char *saved_cache = save_test_env("CBM_CACHE_DIR");
+    cbm_setenv("CBM_CACHE_DIR", cache, 1);
+    char input[1024];
+    snprintf(input, sizeof(input), "{\"hook_event_name\":\"SessionStart\",\"cwd\":\"%s\"}",
+             target_root);
+    char *output = cbm_hook_augment_lifecycle_json(input);
+    bool matched = output && strstr(output, "zzz-custom-project") && strstr(output, "is indexed");
+
+    free(output);
+    restore_test_env("CBM_CACHE_DIR", saved_cache);
+    test_rmdir_r(tmpdir);
+    if (!matched)
+        FAIL("SessionStart must exhaust list_projects pages before resolving root_path");
+    PASS();
+}
+
 TEST(cli_hook_session_sanitizes_untrusted_project_metadata) {
     char tmpdir[256];
     snprintf(tmpdir, sizeof(tmpdir), "/tmp/cli-hook-untrusted-project-XXXXXX");
@@ -9208,6 +9457,56 @@ TEST(cli_hook_augment_context_tracks_search_json_shape) {
     PASS();
 }
 
+TEST(cli_hook_augment_coverage_requests_machine_json) {
+    char tmpdir[256];
+    snprintf(tmpdir, sizeof(tmpdir), "/tmp/cli-hook-coverage-json-XXXXXX");
+    if (!cbm_mkdtemp(tmpdir))
+        FAIL("cbm_mkdtemp failed");
+    char repo[512];
+    char source[640];
+    char db_path[640];
+    snprintf(repo, sizeof(repo), "%s/repo", tmpdir);
+    snprintf(source, sizeof(source), "%s/src/partial.c", repo);
+    snprintf(db_path, sizeof(db_path), "%s/hook.db", tmpdir);
+    test_mkdirp(repo);
+    char source_dir[640];
+    snprintf(source_dir, sizeof(source_dir), "%s/src", repo);
+    test_mkdirp(source_dir);
+    write_test_file(source, "int partial(void) { return 1; }\n");
+
+    cbm_store_t *store = cbm_store_open_path(db_path);
+    ASSERT_NOT_NULL(store);
+    ASSERT_EQ(cbm_store_upsert_project(store, "repo", repo), CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_upsert_file_hash(store, "repo", "src/partial.c", "fixture", 1, 32),
+              CBM_STORE_OK);
+    const cbm_coverage_row_t row = {
+        .rel_path = "src/partial.c", .kind = "parse_partial", .detail = "12-14"};
+    ASSERT_EQ(cbm_store_coverage_replace(store, "repo", &row, 1), CBM_STORE_OK);
+    cbm_store_close(store);
+
+    char *saved_cache = save_test_env("CBM_CACHE_DIR");
+    cbm_setenv("CBM_CACHE_DIR", tmpdir, 1);
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_mcp_server_set_project(srv, "repo");
+
+    char input[2048];
+    snprintf(input, sizeof(input),
+             "{\"hook_event_name\":\"PostToolUse\",\"tool_name\":\"Read\","
+             "\"tool_input\":{\"file_path\":\"%s\"},\"cwd\":\"%s\"}",
+             source, repo);
+    char *output = cbm_hook_augment_process(srv, input);
+    bool matched = output && strstr(output, "PARTIALLY indexed") && strstr(output, "12-14");
+
+    free(output);
+    cbm_mcp_server_free(srv);
+    restore_test_env("CBM_CACHE_DIR", saved_cache);
+    test_rmdir_r(tmpdir);
+    if (!matched)
+        FAIL("Post-read hook must parse check_index_coverage's explicit JSON response");
+    PASS();
+}
+
 TEST(cli_hook_augment_lifecycle_output_contract) {
     static const struct {
         const char *event;
@@ -12071,10 +12370,49 @@ TEST(cli_build_args_json_bad_positional_errors_issue680) {
     PASS();
 }
 
-/* Per-tool --help returns 0 for a known tool, -1 for an unknown one. */
+/* Capture per-tool help using the same tmpfile+dup2 idiom as config-command
+ * output above. This stays portable to the MinGW test leg. */
+static int cli_tool_help_capture(const char *tool_name, char *out, size_t cap) {
+    out[0] = '\0';
+    FILE *capture = tmpfile();
+    int saved = capture ? dup(fileno(stdout)) : -1;
+    if (!capture || saved < 0) {
+        if (capture)
+            fclose(capture);
+        if (saved >= 0)
+            close(saved);
+        return -1000;
+    }
+    fflush(stdout);
+    if (dup2(fileno(capture), fileno(stdout)) < 0) {
+        fclose(capture);
+        close(saved);
+        return -1000;
+    }
+    int rc = cbm_cli_print_tool_help(tool_name);
+    fflush(stdout);
+    (void)dup2(saved, fileno(stdout));
+    close(saved);
+    rewind(capture);
+    size_t got = fread(out, 1, cap - 1, capture);
+    out[got] = '\0';
+    fclose(capture);
+    return rc;
+}
+
+/* Per-tool --help returns 0 for a known tool, -1 for an unknown one, and
+ * surfaces schema choices/defaults rather than flattening every flag to its
+ * primitive JSON type. */
 TEST(cli_print_tool_help_issue680) {
-    ASSERT_EQ(cbm_cli_print_tool_help("index_repository"), 0);
-    ASSERT_EQ(cbm_cli_print_tool_help("nope_not_a_tool"), -1);
+    char out[16 * 1024];
+    ASSERT_EQ(cli_tool_help_capture("search_graph", out, sizeof(out)), 0);
+    ASSERT_NOT_NULL(strstr(out, "--format <tree|json> [default: tree]"));
+    ASSERT_NOT_NULL(strstr(out, "--detail <ids|default> [default: default]"));
+    ASSERT_EQ(cli_tool_help_capture("index_repository", out, sizeof(out)), 0);
+    ASSERT_NOT_NULL(strstr(out, "--mode <full|moderate|fast|cross-repo-intelligence> [default: "
+                                "full]"));
+    ASSERT_EQ(cli_tool_help_capture("nope_not_a_tool", out, sizeof(out)), -1);
+    ASSERT_STR_EQ(out, "");
     PASS();
 }
 
@@ -12408,10 +12746,27 @@ TEST(cli_windows_update_hands_off_to_install_script) {
  * ═══════════════════════════════════════════════════════════════════ */
 
 SUITE(cli) {
+    if (!th_secure_runtime_parent_new(g_cli_suite_runtime_parent,
+                                      sizeof(g_cli_suite_runtime_parent), "cli-suite")) {
+        printf("  %sFAIL%s: could not create private CLI activation runtime\n", tf_red(),
+               tf_reset());
+        tf_fail_count++;
+        return;
+    }
+    cbm_cli_set_activation_runtime_parent_for_test(g_cli_suite_runtime_parent);
+
+    RUN_TEST(cli_suite_uses_private_activation_runtime);
     RUN_TEST(cli_progress_visibility_policy);
+    RUN_TEST(cli_quiet_is_stripped_before_tool_argument_forwarding);
+    RUN_TEST(cli_quiet_rejects_other_outer_output_modes_with_guidance);
+    RUN_TEST(cli_quiet_preserves_tool_level_verbose_argument);
+    RUN_TEST(cli_quiet_suppresses_ordinary_diagnostics_but_preserves_errors);
     RUN_TEST(cli_raw_mcp_result_preserves_tool_error_status);
     RUN_TEST(cli_maintenance_cancellation_forces_failure_status);
     RUN_TEST(cli_progress_sink_accepts_worker_json_logs);
+    RUN_TEST(cli_progress_sink_enables_lifecycle_info_then_restores_quiet_default);
+    RUN_TEST(cli_progress_sink_suppresses_noise_and_preserves_failures);
+    RUN_TEST(cli_progress_sink_preserves_explicit_verbose_diagnostics);
     RUN_TEST(cli_progress_sink_serializes_concurrent_callbacks);
     RUN_TEST(cli_sha256_file_matches_known_vector);
     RUN_TEST(cli_checksum_manifest_requires_exact_filename_and_accepts_star);
@@ -12620,6 +12975,7 @@ SUITE(cli) {
     RUN_TEST(cli_augment_installs_session_context_and_subagent);
     RUN_TEST(cli_augment_session_uses_workspace_roots);
     RUN_TEST(cli_hook_session_resolves_custom_named_index_by_root_path);
+    RUN_TEST(cli_hook_session_exhausts_project_registry_pages);
     RUN_TEST(cli_hook_session_sanitizes_untrusted_project_metadata);
     RUN_TEST(cli_hook_ownership_requires_exact_command_identity);
     RUN_TEST(cli_gemini_hook_upgrade_migrates_released_exact_commands);
@@ -12646,6 +13002,7 @@ SUITE(cli) {
     RUN_TEST(cli_claude_hook_commands_shell_quote_custom_config_dir);
     RUN_TEST(cli_codex_migrates_to_single_hook_representation);
     RUN_TEST(cli_hook_augment_context_tracks_search_json_shape);
+    RUN_TEST(cli_hook_augment_coverage_requests_machine_json);
     RUN_TEST(cli_hook_augment_lifecycle_output_contract);
     RUN_TEST(cli_hook_augment_subagent_tier_router_contract);
     RUN_TEST(cli_hook_augment_subagent_no_project_guidance_is_read_only);
@@ -12768,4 +13125,8 @@ SUITE(cli) {
     RUN_TEST(cli_build_args_json_key_equals_value_issue680);
     RUN_TEST(cli_build_args_json_bad_positional_errors_issue680);
     RUN_TEST(cli_print_tool_help_issue680);
+
+    cbm_cli_set_activation_runtime_parent_for_test(NULL);
+    test_rmdir_r(g_cli_suite_runtime_parent);
+    g_cli_suite_runtime_parent[0] = '\0';
 }
diff --git a/tests/test_cypher.c b/tests/test_cypher.c
index dfe5d3bd7..766f4518a 100644
--- a/tests/test_cypher.c
+++ b/tests/test_cypher.c
@@ -688,9 +688,12 @@ TEST(cypher_exec_optional_saturated_does_not_fabricate_no_match) {
     /* 3 Function nodes → scan_count = 3; max_rows = 3 → bind_cap = 3 and
      * max_new = 30. A alone exceeds that, so B and C are reached with the
      * budget already spent — the regime that produced the fabrication. */
-    cbm_node_t a = {.project = "test", .label = "Function", .name = "A", .qualified_name = "test.A"};
-    cbm_node_t b = {.project = "test", .label = "Function", .name = "B", .qualified_name = "test.B"};
-    cbm_node_t c = {.project = "test", .label = "Function", .name = "C", .qualified_name = "test.C"};
+    cbm_node_t a = {
+        .project = "test", .label = "Function", .name = "A", .qualified_name = "test.A"};
+    cbm_node_t b = {
+        .project = "test", .label = "Function", .name = "B", .qualified_name = "test.B"};
+    cbm_node_t c = {
+        .project = "test", .label = "Function", .name = "C", .qualified_name = "test.C"};
     int64_t a_id = cbm_store_upsert_node(s, &a);
     (void)cbm_store_upsert_node(s, &b); /* B: no outgoing CALLS at all */
     int64_t c_id = cbm_store_upsert_node(s, &c);
@@ -742,6 +745,9 @@ TEST(cypher_exec_optional_saturated_does_not_fabricate_no_match) {
     /* The discriminator: C has 5 callees, so claiming it has none is a
      * fabrication. Pre-fix this is exactly what the saturated path emitted. */
     ASSERT_FALSE(saw_c);
+    /* Late filtering leaves fewer than max_rows output rows, but the earlier
+     * relationship materialization still saturated its candidate budget. */
+    ASSERT_TRUE(r.truncated);
 
     cbm_cypher_result_free(&r);
     cbm_store_close(s);
@@ -1090,6 +1096,9 @@ TEST(cypher_exec_varlength_path_semantics_issue797) {
     ASSERT_EQ(r4.row_count, 0);
     ASSERT_NOT_NULL(r4.warning);
     ASSERT_NOT_NULL(strstr(r4.warning, "clamped"));
+    /* The warning reports the policy clamp, but this shallow fixture has no
+     * candidate beyond the ceiling, so evaluation was still exhaustive. */
+    ASSERT_FALSE(r4.truncated);
     cbm_cypher_result_free(&r4);
 
     cbm_store_close(s);
@@ -1599,6 +1608,7 @@ TEST(cypher_exec_variable_length) {
     ASSERT_EQ(rc, 0);
     /* Should find: ValidateOrder (1 hop), SubmitOrder (2 hops), LogError (1 hop) */
     ASSERT_GTE(r.row_count, 3);
+    ASSERT_FALSE(r.truncated);
 
     cbm_cypher_result_free(&r);
     cbm_store_close(s);
@@ -1666,6 +1676,7 @@ TEST(cypher_exec_var_length_explicit_bound_capped) {
     ASSERT_TRUE(saw_n10);  /* within the ceiling — proves the traversal really ran */
     ASSERT_FALSE(saw_n11); /* clamped away */
     ASSERT_FALSE(saw_n12);
+    ASSERT_TRUE(r.truncated);
 
     cbm_cypher_result_free(&r);
     cbm_store_close(s);
@@ -2460,6 +2471,7 @@ TEST(cypher_apply_limit) {
     int rc = cbm_cypher_execute(s, "MATCH (f:Function) RETURN f.name LIMIT 5", "lim", 0, &r);
     ASSERT_EQ(rc, 0);
     ASSERT_EQ(r.row_count, 5);
+    ASSERT_FALSE(r.truncated);
     cbm_cypher_result_free(&r);
 
     /* No LIMIT, max_rows=10 → capped at 10 */
@@ -2467,6 +2479,7 @@ TEST(cypher_apply_limit) {
     rc = cbm_cypher_execute(s, "MATCH (f:Function) RETURN f.name", "lim", 10, &r);
     ASSERT_EQ(rc, 0);
     ASSERT_EQ(r.row_count, 10);
+    ASSERT_TRUE(r.truncated);
     cbm_cypher_result_free(&r);
 
     /* LIMIT above max_rows → explicit limit wins */
@@ -2474,12 +2487,142 @@ TEST(cypher_apply_limit) {
     rc = cbm_cypher_execute(s, "MATCH (f:Function) RETURN f.name LIMIT 30", "lim", 10, &r);
     ASSERT_EQ(rc, 0);
     ASSERT_EQ(r.row_count, 30);
+    ASSERT_FALSE(r.truncated);
     cbm_cypher_result_free(&r);
 
     cbm_store_close(s);
     PASS();
 }
 
+/* max_rows is an engine output budget, not Cypher query semantics. Callers
+ * need to distinguish a complete short result from one cut off by that budget.
+ * An explicit LIMIT remains complete because it is part of the query itself. */
+TEST(cypher_result_reports_max_rows_saturation) {
+    cbm_store_t *s = cbm_store_open_memory();
+    cbm_store_upsert_project(s, "sat", "/tmp/sat");
+
+    for (int i = 0; i < 7; i++) {
+        char name[32];
+        char qn[64];
+        snprintf(name, sizeof(name), "func%d", i);
+        snprintf(qn, sizeof(qn), "sat.func%d", i);
+        cbm_node_t n = {.project = "sat",
+                        .label = "Function",
+                        .name = name,
+                        .qualified_name = qn,
+                        .file_path = "test.c"};
+        cbm_store_upsert_node(s, &n);
+    }
+
+    cbm_cypher_result_t r = {0};
+    int rc = cbm_cypher_execute(s, "MATCH (f:Function) RETURN f.name", "sat", 3, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 3);
+    ASSERT_TRUE(r.truncated);
+    cbm_cypher_result_free(&r);
+
+    memset(&r, 0, sizeof(r));
+    rc = cbm_cypher_execute(s, "MATCH (f:Function) RETURN f.name", "sat", 10, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 7);
+    ASSERT_FALSE(r.truncated);
+    cbm_cypher_result_free(&r);
+
+    memset(&r, 0, sizeof(r));
+    rc = cbm_cypher_execute(s, "MATCH (f:Function) RETURN f.name LIMIT 3", "sat", 10, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 3);
+    ASSERT_FALSE(r.truncated);
+    cbm_cypher_result_free(&r);
+
+    /* RETURN * historically keeps max_rows as its output cap even when a
+     * larger Cypher LIMIT is present; preserve that behavior and report it. */
+    memset(&r, 0, sizeof(r));
+    rc = cbm_cypher_execute(s, "MATCH (f:Function) RETURN * LIMIT 5", "sat", 3, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 3);
+    ASSERT_TRUE(r.truncated);
+    cbm_cypher_result_free(&r);
+
+    cbm_store_close(s);
+    PASS();
+}
+
+/* An unlabeled scan has a max_rows*10 candidate budget. Aggregation can hide
+ * that loss behind one output row, so row_count alone cannot report it. */
+TEST(cypher_result_reports_scan_saturation_before_aggregation) {
+    cbm_store_t *s = cbm_store_open_memory();
+    cbm_store_upsert_project(s, "scan_sat", "/tmp/scan_sat");
+
+    for (int i = 0; i < 11; i++) {
+        char name[32];
+        char qn[64];
+        snprintf(name, sizeof(name), "node%d", i);
+        snprintf(qn, sizeof(qn), "scan_sat.node%d", i);
+        cbm_node_t n = {
+            .project = "scan_sat", .label = "Function", .name = name, .qualified_name = qn};
+        cbm_store_upsert_node(s, &n);
+    }
+
+    cbm_cypher_result_t r = {0};
+    int rc = cbm_cypher_execute(s, "MATCH (n) RETURN count(*) AS n", "scan_sat", 1, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 1);
+    ASSERT_STR_EQ(r.rows[0][0], "10");
+    ASSERT_TRUE(r.truncated);
+    cbm_cypher_result_free(&r);
+
+    memset(&r, 0, sizeof(r));
+    rc = cbm_cypher_execute(s, "MATCH (n) RETURN count(*) AS n", "scan_sat", 2, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 1);
+    ASSERT_STR_EQ(r.rows[0][0], "11");
+    ASSERT_FALSE(r.truncated);
+    cbm_cypher_result_free(&r);
+
+    cbm_store_close(s);
+    PASS();
+}
+
+/* Variable-length traversal historically materializes at most 100 visited
+ * nodes. Probe one extra candidate so an exact 100 is distinguishable from a
+ * graph with additional reachable nodes, while preserving the 100-row output. */
+TEST(cypher_result_reports_variable_length_candidate_saturation) {
+    cbm_store_t *s = cbm_store_open_memory();
+    cbm_store_upsert_project(s, "bfs_sat", "/tmp/bfs_sat");
+
+    cbm_node_t root = {.project = "bfs_sat",
+                       .label = "Function",
+                       .name = "root",
+                       .qualified_name = "bfs_sat.root"};
+    int64_t root_id = cbm_store_upsert_node(s, &root);
+    for (int i = 0; i < 101; i++) {
+        char name[32];
+        char qn[64];
+        snprintf(name, sizeof(name), "target%03d", i);
+        snprintf(qn, sizeof(qn), "bfs_sat.target%03d", i);
+        cbm_node_t target = {
+            .project = "bfs_sat", .label = "Var", .name = name, .qualified_name = qn};
+        int64_t target_id = cbm_store_upsert_node(s, &target);
+        cbm_edge_t edge = {
+            .project = "bfs_sat", .source_id = root_id, .target_id = target_id, .type = "CALLS"};
+        cbm_store_insert_edge(s, &edge);
+    }
+
+    cbm_cypher_result_t r = {0};
+    int rc = cbm_cypher_execute(s,
+                                "MATCH (a:Function {name: \"root\"})-[:CALLS*1..2]->(b:Var) "
+                                "RETURN b.name",
+                                "bfs_sat", 1000, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 100);
+    ASSERT_TRUE(r.truncated);
+
+    cbm_cypher_result_free(&r);
+    cbm_store_close(s);
+    PASS();
+}
+
 /* ══════════════════════════════════════════════════════════════════
  *  PHASE 1: SIMPLE OPERATORS
  * ══════════════════════════════════════════════════════════════════ */
@@ -2890,11 +3033,10 @@ TEST(cypher_exec_multikey_order_by_keeps_limit_issue1334) {
     cbm_store_t *s = setup_cypher_store();
     cbm_cypher_result_t r = {0};
     /* start_lines: HandleOrder=10, ValidateOrder=5, SubmitOrder=0, LogError=0 */
-    int rc = cbm_cypher_execute(
-        s,
-        "MATCH (f:Function) RETURN f.name, f.start_line "
-        "ORDER BY f.start_line DESC, f.name ASC LIMIT 2",
-        "test", 0, &r);
+    int rc = cbm_cypher_execute(s,
+                                "MATCH (f:Function) RETURN f.name, f.start_line "
+                                "ORDER BY f.start_line DESC, f.name ASC LIMIT 2",
+                                "test", 0, &r);
     ASSERT_EQ(rc, 0);
     ASSERT_EQ(r.row_count, 2);
     ASSERT_STR_EQ(r.rows[0][0], "HandleOrder");
@@ -2910,11 +3052,10 @@ TEST(cypher_exec_multikey_order_by_tiebreak_issue1334) {
     cbm_cypher_result_t r = {0};
     /* start_line ASC puts the two 0-line functions first; name DESC breaks the
      * tie: SubmitOrder before LogError. */
-    int rc = cbm_cypher_execute(
-        s,
-        "MATCH (f:Function) RETURN f.name, f.start_line "
-        "ORDER BY f.start_line ASC, f.name DESC LIMIT 2",
-        "test", 0, &r);
+    int rc = cbm_cypher_execute(s,
+                                "MATCH (f:Function) RETURN f.name, f.start_line "
+                                "ORDER BY f.start_line ASC, f.name DESC LIMIT 2",
+                                "test", 0, &r);
     ASSERT_EQ(rc, 0);
     ASSERT_EQ(r.row_count, 2);
     ASSERT_STR_EQ(r.rows[0][0], "SubmitOrder");
@@ -3239,8 +3380,7 @@ TEST(cypher_issue1111_with_type_count_group) {
     cbm_store_t *s = setup_cypher_store();
     cbm_cypher_result_t r = {0};
     int rc = cbm_cypher_execute(
-        s,
-        "MATCH (a)-[r]->(b) WITH type(r) AS t, count(*) AS n RETURN t, n ORDER BY n DESC",
+        s, "MATCH (a)-[r]->(b) WITH type(r) AS t, count(*) AS n RETURN t, n ORDER BY n DESC",
         "test", 0, &r);
     ASSERT_EQ(rc, 0);
     ASSERT_EQ(r.row_count, 2);
@@ -3943,6 +4083,9 @@ SUITE(cypher) {
     RUN_TEST(cypher_edge_filter_regex);
     RUN_TEST(cypher_edge_builtin_type_filter);
     RUN_TEST(cypher_apply_limit);
+    RUN_TEST(cypher_result_reports_max_rows_saturation);
+    RUN_TEST(cypher_result_reports_scan_saturation_before_aggregation);
+    RUN_TEST(cypher_result_reports_variable_length_candidate_saturation);
     /* Phase 1: Simple operators */
     RUN_TEST(cypher_lex_neq_operators);
     RUN_TEST(cypher_lex_ends_keyword);
diff --git a/tests/test_daemon_runtime.c b/tests/test_daemon_runtime.c
index 5f41d914e..ff7017160 100644
--- a/tests/test_daemon_runtime.c
+++ b/tests/test_daemon_runtime.c
@@ -2076,6 +2076,8 @@ TEST(daemon_runtime_activation_ack_snapshots_then_interrupts_all_clients) {
     bool second_interrupted = false;
     bool exited = false;
     atomic_store_explicit(&runtime_activation_shutdown_log_seen, false, memory_order_release);
+    CBMLogLevel previous_log_level = cbm_log_get_level();
+    cbm_log_set_level(CBM_LOG_INFO);
     cbm_log_set_sink(runtime_test_activation_shutdown_sink);
 
     if (started) {
@@ -2092,6 +2094,7 @@ TEST(daemon_runtime_activation_ack_snapshots_then_interrupts_all_clients) {
         second_interrupted = !cbm_daemon_runtime_client_heartbeat(second, RUNTIME_TEST_TIMEOUT_MS);
     }
     cbm_log_set_sink(NULL);
+    cbm_log_set_level(previous_log_level);
     if (first) {
         (void)cbm_daemon_runtime_client_close(first, RUNTIME_TEST_TIMEOUT_MS);
         first = NULL;
diff --git a/tests/test_diagnostics.c b/tests/test_diagnostics.c
index e05677fd3..fa6a35c7e 100644
--- a/tests/test_diagnostics.c
+++ b/tests/test_diagnostics.c
@@ -359,6 +359,7 @@ static bool diagnostics_discovery_value(const char *key, char *out, size_t out_s
 TEST(diagnostics_discovery_record_survives_suppressed_log_level) {
     diagnostics_discovery_records = 0;
     diagnostics_discovery_line[0] = '\0';
+    CBMLogLevel previous_log_level = cbm_log_get_level();
     cbm_log_set_level(CBM_LOG_NONE);
     cbm_log_set_sink_ex(diagnostics_discovery_sink, CBM_LOG_SINK_REPLACE);
     ASSERT_EQ(cbm_setenv("CBM_DIAGNOSTICS", "1", 1), 0);
@@ -368,7 +369,7 @@ TEST(diagnostics_discovery_record_survives_suppressed_log_level) {
     cbm_diag_stop();
     (void)cbm_unsetenv("CBM_DIAGNOSTICS");
     cbm_log_set_sink(NULL);
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(previous_log_level);
 
     char recorded_snapshot[1024] = "";
     char recorded_trajectory[1024] = "";
diff --git a/tests/test_httpd.c b/tests/test_httpd.c
index 0d2f82402..193a57873 100644
--- a/tests/test_httpd.c
+++ b/tests/test_httpd.c
@@ -1086,19 +1086,26 @@ TEST(ui_server_mutations_require_json_content_type) {
 TEST(ui_server_rpc_allows_only_ui_read_tools) {
     th_server_t ts;
     ASSERT_EQ(th_server_start(&ts), 0);
-    const char *body = "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\","
-                       "\"params\":{\"name\":\"list_projects\",\"arguments\":{}}}";
     char req[1024];
-    snprintf(req, sizeof(req),
-             "POST /rpc HTTP/1.1\r\n"
-             "Content-Type: application/json\r\n"
-             "Content-Length: %d\r\n\r\n%s",
-             (int)strlen(body), body);
     char resp[8192];
-    int n = th_http(cbm_http_server_port(ts.srv), req, resp, sizeof(resp));
-    ASSERT_GT(n, 0);
-    ASSERT_EQ(th_status(resp), 200);
-    ASSERT_NOT_NULL(strstr(resp, "\"jsonrpc\""));
+    int n = 0;
+    static const char *allowed_tools[] = {"list_projects", "get_graph_schema", "get_code_snippet"};
+    for (size_t i = 0; i < sizeof(allowed_tools) / sizeof(allowed_tools[0]); i++) {
+        char body[512];
+        snprintf(body, sizeof(body),
+                 "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\","
+                 "\"params\":{\"name\":\"%s\",\"arguments\":{}}}",
+                 allowed_tools[i]);
+        snprintf(req, sizeof(req),
+                 "POST /rpc HTTP/1.1\r\n"
+                 "Content-Type: application/json\r\n"
+                 "Content-Length: %zu\r\n\r\n%s",
+                 strlen(body), body);
+        n = th_http(cbm_http_server_port(ts.srv), req, resp, sizeof(resp));
+        ASSERT_GT(n, 0);
+        ASSERT_EQ(th_status(resp), 200);
+        ASSERT_NOT_NULL(strstr(resp, "\"jsonrpc\""));
+    }
 
     static const char *blocked_tools[] = {"delete_project", "manage_adr", "ingest_traces",
                                           "index_repository"};
diff --git a/tests/test_incremental.c b/tests/test_incremental.c
index 7ae91f971..498d912b9 100644
--- a/tests/test_incremental.c
+++ b/tests/test_incremental.c
@@ -916,6 +916,16 @@ TEST(incr_perf_single_file_fast) {
     }
 
     delete_file_at("fastapi/incr_perf_probe.py");
+    /* Publish the cleanup too. search_code now consumes the complete scoped
+     * file list and fails closed when the graph names a source file that grep
+     * cannot read; leaving this probe indexed would make every later matching
+     * search correctly report an incomplete snapshot instead of exercising
+     * the search parameter contract this fixture is meant to cover. The
+     * cleanup reindex is deliberately outside the measured interval above. */
+    resp = index_repo();
+    ASSERT(resp != NULL);
+    ASSERT(strstr(resp, "indexed") != NULL);
+    free(resp);
     PASS();
 }
 
@@ -1568,26 +1578,29 @@ TEST(tool_qg_two_hop) {
 
 TEST(tool_qg_max_rows) {
     double ms;
-    /* Query without max_rows — gets many results */
+    /* Query without max_rows — its explicit Cypher LIMIT is the visible cap. */
     char *r1 = call_tool_timed("query_graph", &ms,
                                "{\"project\":\"%s\","
                                "\"query\":\"MATCH (n:Function) RETURN n.name LIMIT 100\"}",
                                g_project);
     TOOL_OK(r1, ms);
-    int total_unlimited = count_in_response(r1, "total");
+    int returned_unlimited = count_in_response(r1, "returned");
     free(r1);
 
-    /* Same query without LIMIT but with max_rows=3 — must cap results */
+    /* max_rows caps presentation, not evaluation: returned is bounded while
+     * total remains the exact full materialized count. */
     char *r2 = call_tool_timed("query_graph", &ms,
                                "{\"project\":\"%s\","
                                "\"query\":\"MATCH (n:Function) RETURN n.name\","
                                "\"max_rows\":3}",
                                g_project);
     TOOL_OK(r2, ms);
+    int returned_limited = count_in_response(r2, "returned");
     int total_limited = count_in_response(r2, "total");
-    ASSERT_LTE(total_limited, 3);
-    /* Without max_rows should have more than with */
-    ASSERT_GT(total_unlimited, total_limited);
+    ASSERT_EQ(returned_limited, 3);
+    ASSERT_GT(total_limited, returned_limited);
+    ASSERT_GT(returned_unlimited, returned_limited);
+    ASSERT_NOT_NULL(strstr(r2, "page_limit"));
     free(r2);
     PASS();
 }
@@ -1908,12 +1921,22 @@ TEST(tool_arch_no_aspects) {
 
 TEST(tool_detect_changes_default) {
     double ms;
-    char *r = call_tool_timed("detect_changes", &ms, "{\"project\":\"%s\"}", g_project);
+    /* The fixture is intentionally detached, so pin only the base while
+     * exercising every other default (scope, direction, depth, and budget). */
+    char *r = call_tool_timed("detect_changes", &ms,
+                              "{\"project\":\"%s\",\"base_branch\":\"HEAD\"}", g_project);
     TOOL_OK(r, ms);
-    /* New tree contract: base + direction scalars, a changed_files section,
-     * and the seed/impact accounting. (The old changed_count/impacted_symbols/
-     * depth keys are gone — impact is now a real traversal, not bare names.) */
-    ASSERT(strstr(r, "changed_files:") != NULL);
+    NOT_ERROR(r);
+    /* Lean tree contract: preserve exact changed-file accounting, but do not
+     * spend tokens on a zero-row table. A non-empty page still carries the
+     * changed_files rows; an empty page is represented by its exact scalars. */
+    int changed_total = count_in_response(r, "changed_total");
+    int changed_returned = count_in_response(r, "changed_returned");
+    ASSERT_GTE(changed_total, 0);
+    ASSERT_GTE(changed_returned, 0);
+    ASSERT_LTE(changed_returned, changed_total);
+    ASSERT(changed_returned > 0 ? resp_has_key(r, "changed_files")
+                                : resp_lacks_key(r, "changed_files"));
     ASSERT(strstr(r, "direction:") != NULL);
     ASSERT(strstr(r, "seed_symbols:") != NULL);
     free(r);
@@ -1961,7 +1984,15 @@ TEST(tool_detect_changes_since) {
     char *r = call_tool_timed("detect_changes", &ms, "{\"project\":\"%s\",\"since\":\"HEAD\"}",
                               g_project);
     TOOL_OK(r, ms);
-    ASSERT(resp_has_key(r, "changed_files"));
+    NOT_ERROR(r);
+    ASSERT(strstr(r, "base: HEAD") != NULL);
+    int changed_total = count_in_response(r, "changed_total");
+    int changed_returned = count_in_response(r, "changed_returned");
+    ASSERT_GTE(changed_total, 0);
+    ASSERT_GTE(changed_returned, 0);
+    ASSERT_LTE(changed_returned, changed_total);
+    ASSERT(changed_returned > 0 ? resp_has_key(r, "changed_files")
+                                : resp_lacks_key(r, "changed_files"));
     free(r);
     PASS();
 }
@@ -2262,8 +2293,11 @@ TEST(tool_qg_max_rows_1) {
                               "\"max_rows\":1}",
                               g_project);
     TOOL_OK(r, ms);
+    int returned = count_in_response(r, "returned");
     int total = count_in_response(r, "total");
-    ASSERT_EQ(total, 1);
+    ASSERT_EQ(returned, 1);
+    ASSERT_GT(total, returned);
+    ASSERT_NOT_NULL(strstr(r, "page_limit"));
     free(r);
     PASS();
 }
diff --git a/tests/test_index_resilience.c b/tests/test_index_resilience.c
index 8d8a601a6..28664f033 100644
--- a/tests/test_index_resilience.c
+++ b/tests/test_index_resilience.c
@@ -392,7 +392,7 @@ TEST(index_parse_partial_reported) {
     ASSERT_TRUE(marked);
 
     char qargs[900];
-    snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\"}", lp.project);
+    snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\",\"diagnostics\":\"full\"}", lp.project);
     char *qresp = cbm_mcp_handle_tool(lp.srv, "index_status", qargs);
     ASSERT_NOT_NULL(qresp);
     ASSERT_NOT_NULL(strstr(qresp, "split.c"));
@@ -488,7 +488,7 @@ TEST(index_parse_partial_clears_on_fix) {
 
     /* Flagged after the first (full) index. */
     char qargs[900];
-    snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\"}", lp.project);
+    snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\",\"diagnostics\":\"full\"}", lp.project);
     char *cov1 = cbm_mcp_handle_tool(lp.srv, "index_status", qargs);
     ASSERT_NOT_NULL(cov1);
     ASSERT_NOT_NULL(strstr(cov1, "flaky.c"));
@@ -607,7 +607,7 @@ TEST(index_not_indexed_by_design_reported) {
 
     /* index_status carries the persisted by-design section. */
     char qargs[900];
-    snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\"}", lp.project);
+    snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\",\"diagnostics\":\"full\"}", lp.project);
     char *sresp = cbm_mcp_handle_tool(lp.srv, "index_status", qargs);
     ASSERT_NOT_NULL(sresp);
     ASSERT_NOT_NULL(strstr(sresp, "not_indexed"));
@@ -635,6 +635,7 @@ TEST(index_not_indexed_by_design_reported) {
     char *resp2 = cbm_mcp_handle_tool(lp.srv, "index_repository", iargs);
     ASSERT_NOT_NULL(resp2);
     free(resp2);
+    snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\",\"diagnostics\":\"full\"}", lp.project);
     char *sresp2 = cbm_mcp_handle_tool(lp.srv, "index_status", qargs);
     ASSERT_NOT_NULL(sresp2);
     ASSERT_NOT_NULL(strstr(sresp2, "secret.py"));
diff --git a/tests/test_index_supervisor.c b/tests/test_index_supervisor.c
index d94fe7329..f259d3bdb 100644
--- a/tests/test_index_supervisor.c
+++ b/tests/test_index_supervisor.c
@@ -643,6 +643,50 @@ TEST(index_supervisor_terminal_log_lifecycle_matches_outcome_and_profiling) {
     PASS();
 }
 
+TEST(index_supervisor_worker_keeps_default_info_liveness_heartbeat) {
+    char cache[INDEX_SUPERVISOR_TEST_PATH_CAP];
+    (void)snprintf(cache, sizeof(cache), "%s/cbm-index-heartbeat-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+    const char *old_cache = getenv("CBM_CACHE_DIR");
+    const char *old_log_level = getenv("CBM_LOG_LEVEL");
+    char *saved_cache = old_cache ? cbm_strdup(old_cache) : NULL;
+    char *saved_log_level = old_log_level ? cbm_strdup(old_log_level) : NULL;
+    (void)cbm_setenv("CBM_CACHE_DIR", cache, 1);
+    (void)cbm_unsetenv("CBM_LOG_LEVEL");
+
+    cbm_index_worker_handle_t *handle = NULL;
+    int start_rc = cbm_index_worker_start("{\"__cbm_test_worker\":\"heartbeat\"}", 0, false,
+                                          NULL, NULL, &handle);
+    char log_path[INDEX_SUPERVISOR_TEST_PATH_CAP] = {0};
+    if (handle) {
+        (void)snprintf(log_path, sizeof(log_path), "%s", cbm_index_worker_log_path(handle));
+    }
+    bool ready = log_path[0] && index_supervisor_test_wait_file_text(
+                                    log_path, "async worker heartbeat probe ready",
+                                    INDEX_SUPERVISOR_TEST_READY_MS);
+    bool heartbeat = ready && index_supervisor_test_wait_file_text(
+                                  log_path, "msg=pipeline.discover", 1000);
+    const cbm_index_worker_result_t *result = NULL;
+    bool terminal = handle && index_supervisor_test_poll_terminal(
+                                  handle, INDEX_SUPERVISOR_TEST_TERMINAL_MS, &result);
+    bool clean = terminal && result && result->outcome == CBM_PROC_CLEAN && result->response;
+    if (terminal) {
+        cbm_index_worker_destroy(handle);
+    } else {
+        index_supervisor_test_dump("heartbeat worker log", log_path);
+        index_supervisor_test_cleanup_handle(handle);
+    }
+    index_supervisor_test_restore_env("CBM_LOG_LEVEL", saved_log_level);
+    index_supervisor_test_restore_env("CBM_CACHE_DIR", saved_cache);
+    (void)th_rmtree(cache);
+
+    ASSERT_EQ(start_rc, 0);
+    ASSERT_TRUE(ready);
+    ASSERT_TRUE(heartbeat);
+    ASSERT_TRUE(clean);
+    PASS();
+}
+
 TEST(index_supervisor_drains_terminal_backlog_into_request_progress_callback) {
     char cache[INDEX_SUPERVISOR_TEST_PATH_CAP];
     (void)snprintf(cache, sizeof(cache), "%s/cbm-index-relay-XXXXXX", cbm_tmpdir());
@@ -767,6 +811,7 @@ SUITE(index_supervisor) {
     RUN_TEST(index_supervisor_async_jobs_are_isolated_cancellable_and_terminal_cached);
     RUN_TEST(index_supervisor_sync_wrapper_forwards_cancel_and_drains_tree);
     RUN_TEST(index_supervisor_terminal_log_lifecycle_matches_outcome_and_profiling);
+    RUN_TEST(index_supervisor_worker_keeps_default_info_liveness_heartbeat);
     RUN_TEST(index_supervisor_drains_terminal_backlog_into_request_progress_callback);
     RUN_TEST(index_supervisor_oversized_response_is_contained_and_log_is_retained);
 }
diff --git a/tests/test_log.c b/tests/test_log.c
index 562768567..d52d27c88 100644
--- a/tests/test_log.c
+++ b/tests/test_log.c
@@ -55,15 +55,50 @@ static const char *capture_end(void) {
 }
 
 TEST(log_level_default) {
-    /* Default level should be INFO */
+    /* Raw startup is quiet until main applies its role-aware policy. */
+    ASSERT_EQ(cbm_log_get_level(), CBM_LOG_WARN);
+    PASS();
+}
+
+TEST(log_level_env_keeps_info_and_debug_opt_in) {
+    cbm_setenv("CBM_LOG_LEVEL", "info", 1);
+    cbm_log_init_from_env();
+    ASSERT_EQ(cbm_log_get_level(), CBM_LOG_INFO);
+
+    cbm_setenv("CBM_LOG_LEVEL", "debug", 1);
+    cbm_log_init_from_env();
+    ASSERT_EQ(cbm_log_get_level(), CBM_LOG_DEBUG);
+
+    cbm_unsetenv("CBM_LOG_LEVEL");
+    cbm_log_set_level(CBM_LOG_WARN);
+    PASS();
+}
+
+TEST(log_startup_policy_keeps_frontends_quiet_and_workers_live) {
+    cbm_unsetenv("CBM_LOG_LEVEL");
+    cbm_log_init_for_process(true, false);
+    ASSERT_EQ(cbm_log_get_level(), CBM_LOG_WARN);
+
+    cbm_log_init_for_process(false, true);
+    ASSERT_EQ(cbm_log_get_level(), CBM_LOG_INFO);
+
+    cbm_setenv("CBM_LOG_LEVEL", "none", 1);
+    cbm_log_init_for_process(false, true);
     ASSERT_EQ(cbm_log_get_level(), CBM_LOG_INFO);
+
+    cbm_setenv("CBM_LOG_LEVEL", "debug", 1);
+    cbm_log_init_for_process(true, false);
+    ASSERT_EQ(cbm_log_get_level(), CBM_LOG_DEBUG);
+
+    cbm_unsetenv("CBM_LOG_LEVEL");
+    cbm_log_set_level(CBM_LOG_WARN);
     PASS();
 }
 
 TEST(log_level_set) {
     cbm_log_set_level(CBM_LOG_WARN);
     ASSERT_EQ(cbm_log_get_level(), CBM_LOG_WARN);
-    cbm_log_set_level(CBM_LOG_INFO); /* restore */
+    cbm_log_set_level(CBM_LOG_WARN); /* restore */
     PASS();
 }
 
@@ -72,7 +107,7 @@ TEST(log_info_output) {
     capture_start();
     cbm_log_info("test.msg", "key1", "val1", "key2", "val2");
     const char *output = capture_end();
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(CBM_LOG_WARN);
 
     ASSERT(cbm_str_contains_raw(output, "level=info"));
     ASSERT(cbm_str_contains_raw(output, "msg=test.msg"));
@@ -86,7 +121,7 @@ TEST(log_filtered_by_level) {
     capture_start();
     cbm_log_info("should.not.appear");
     const char *output = capture_end();
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(CBM_LOG_WARN);
 
     /* Should be empty — info is below warn threshold */
     ASSERT_EQ(strlen(output), 0);
@@ -98,7 +133,7 @@ TEST(log_error_output) {
     capture_start();
     cbm_log_error("critical.fail", "err", "OOM");
     const char *output = capture_end();
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(CBM_LOG_WARN);
 
     ASSERT(cbm_str_contains_raw(output, "level=error"));
     ASSERT(cbm_str_contains_raw(output, "msg=critical.fail"));
@@ -111,7 +146,7 @@ TEST(log_int_helper) {
     capture_start();
     cbm_log_int(CBM_LOG_INFO, "pass.timing", "elapsed_ms", 42);
     const char *output = capture_end();
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(CBM_LOG_WARN);
 
     ASSERT(cbm_str_contains_raw(output, "elapsed_ms=42"));
     PASS();
@@ -124,7 +159,7 @@ TEST(log_json_output) {
     cbm_log_info("test.msg", "key1", "val1", "key2", "line\nbreak");
     const char *output = capture_end();
     cbm_log_set_format(CBM_LOG_FORMAT_TEXT);
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(CBM_LOG_WARN);
 
     ASSERT(cbm_str_contains_raw(output, "\"level\":\"info\""));
     ASSERT(cbm_str_contains_raw(output, "\"event\":\"test.msg\""));
@@ -139,7 +174,7 @@ TEST(log_text_sanitizes_control_chars) {
     capture_start();
     cbm_log_info("test\nmsg", "key", "line\r\nbreak\tvalue");
     const char *output = capture_end();
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(CBM_LOG_WARN);
 
     ASSERT(cbm_str_contains_raw(output, "msg=test_msg"));
     ASSERT(cbm_str_contains_raw(output, "key=line__break_value"));
@@ -157,7 +192,7 @@ TEST(log_sink_tee_keeps_stderr) {
     cbm_log_info("tee.msg", "key", "val");
     const char *output = capture_end();
     cbm_log_set_sink(NULL);
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(CBM_LOG_WARN);
 
     ASSERT(cbm_str_contains_raw(output, "msg=tee.msg"));
     ASSERT(cbm_str_contains_raw(sink_buf, "msg=tee.msg"));
@@ -171,7 +206,7 @@ TEST(log_operational_helpers) {
     cbm_log_mcp_request("tools/call", "search_graph", false, 1250);
     cbm_log_http_request("graph_ui", "GET", "/api/layout", 200, 7, 0, 42);
     const char *output = capture_end();
-    cbm_log_set_level(CBM_LOG_INFO);
+    cbm_log_set_level(CBM_LOG_WARN);
 
     ASSERT(cbm_str_contains_raw(output, "msg=mcp.request"));
     ASSERT(cbm_str_contains_raw(output, "protocol=jsonrpc"));
@@ -235,7 +270,7 @@ TEST(log_level_from_env_textual) {
     ASSERT_EQ(cbm_log_get_level(), CBM_LOG_INFO);
 
     cbm_unsetenv("CBM_LOG_LEVEL");
-    cbm_log_set_level(CBM_LOG_INFO); /* restore */
+    cbm_log_set_level(CBM_LOG_WARN); /* restore */
     PASS();
 }
 
@@ -260,7 +295,7 @@ TEST(log_level_from_env_numeric) {
     ASSERT_EQ(cbm_log_get_level(), CBM_LOG_INFO);
 
     cbm_unsetenv("CBM_LOG_LEVEL");
-    cbm_log_set_level(CBM_LOG_INFO); /* restore */
+    cbm_log_set_level(CBM_LOG_WARN); /* restore */
     PASS();
 }
 
@@ -279,12 +314,14 @@ TEST(log_level_from_env_invalid_ignored) {
     cbm_log_init_from_env();
     ASSERT_EQ(cbm_log_get_level(), CBM_LOG_WARN);
 
-    cbm_log_set_level(CBM_LOG_INFO); /* restore */
+    cbm_log_set_level(CBM_LOG_WARN); /* restore */
     PASS();
 }
 
 SUITE(log) {
     RUN_TEST(log_level_default);
+    RUN_TEST(log_level_env_keeps_info_and_debug_opt_in);
+    RUN_TEST(log_startup_policy_keeps_frontends_quiet_and_workers_live);
     RUN_TEST(log_level_set);
     RUN_TEST(log_info_output);
     RUN_TEST(log_filtered_by_level);
diff --git a/tests/test_main.c b/tests/test_main.c
index 120c036b2..9f855d1c1 100644
--- a/tests/test_main.c
+++ b/tests/test_main.c
@@ -14,6 +14,7 @@ int tf_skip_count = 0;
 #include "foundation/compat.h"     /* cbm_setenv — #845 supervisor kill switch */
 #include "foundation/compat_fs.h"  /* cbm_fopen — worker response file */
 #include "foundation/mem.h"        /* cbm_mem_init — worker budget */
+#include "foundation/log.h"        /* worker liveness heartbeat probe */
 #include "foundation/platform.h"   /* cbm_file_exists — blocking-git marker */
 #include "daemon/runtime.h"        /* bounded worker response probe */
 #include "daemon/ipc.h"            /* Windows private-lock re-exec probe */
@@ -195,6 +196,17 @@ static void tf_index_worker_probe(const char *args_json, const char *response_ou
         fflush(NULL);
         _Exit(response ? 0 : 1);
     }
+    if (strstr(args_json, "\"heartbeat\"")) {
+        FILE *response = response_out ? cbm_fopen(response_out, "wb") : NULL;
+        if (response) {
+            (void)fputs("{\"probe\":\"heartbeat\"}", response);
+            (void)fclose(response);
+        }
+        cbm_log_info("pipeline.discover", "files", "1");
+        (void)fprintf(stderr, "async worker heartbeat probe ready\n");
+        fflush(NULL);
+        _Exit(response ? 0 : 1);
+    }
     if (strstr(args_json, "\"crash\"")) {
         (void)fprintf(stderr, "async worker crash probe\n");
         fflush(NULL);
@@ -269,6 +281,7 @@ static int tf_maybe_run_index_worker(int argc, char **argv) {
                                       invocation.marker_file, invocation.quarantine_file,
                                       invocation.memory_budget_bytes);
     cbm_mem_init_with_cap(0.5, invocation.memory_budget_bytes);
+    cbm_log_init_for_process(false, true);
     tf_index_worker_probe(invocation.args_json, invocation.response_out);
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     if (!srv) {
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 1d99d71ad..c3d47f1da 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -187,6 +187,11 @@ static bool mcp_command_hook_probe(void *context, const char *command) {
     return true;
 }
 
+static bool mcp_snapshot_read_hook_probe(void *context, const char *absolute_path) {
+    const char *rejected_fragment = context;
+    return !rejected_fragment || !absolute_path || !strstr(absolute_path, rejected_fragment);
+}
+
 typedef struct {
     const char *name;
     char *value;
@@ -513,7 +518,7 @@ static int mcp_count_corrupt_artifacts(const char *cache, const char *project) {
 static int mcp_count_directory_entries_with_prefix(const char *directory, const char *prefix) {
     cbm_dir_t *dir = cbm_opendir(directory);
     if (!dir) {
-        return -1;
+        return 0;
     }
     size_t prefix_length = strlen(prefix);
     int count = 0;
@@ -574,12 +579,14 @@ static void mcp_replacing_mutation_guard_end(void *context, const char *project)
     }
 }
 
-TEST(tree_cell_sanitizes_control_and_invalid_utf8) {
+TEST(tree_cell_reversibly_encodes_invalid_utf8) {
     /* One raw control or invalid-UTF8 byte in a cell poisons LINE-ORIENTED
      * consumers of the ENTIRE output (BSD grep treats all of it as
      * unmatchable binary — the macos-15-intel release-smoke B3 class), so
-     * cell emission guarantees valid UTF-8: control bytes escape as \u00XX,
-     * invalid sequences become U+FFFD, and both force the quoted form. */
+     * cell emission guarantees valid UTF-8 without losing identity: an
+     * invalid string is encoded in full as @bytes:<lowercase hex>. A valid
+     * string beginning with that reserved prefix is escaped as @utf8:<text>,
+     * so a consumer can always distinguish data from an encoded byte string. */
     cbm_sb_t sb;
     cbm_sb_init(&sb);
     cbm_tree_cell_str(&sb,
@@ -588,8 +595,14 @@ TEST(tree_cell_sanitizes_control_and_invalid_utf8) {
                       true);
     char *out = cbm_sb_finish(&sb);
     ASSERT_NOT_NULL(out);
-    ASSERT_STR_EQ(out, "\"evil\\u0001name\xEF\xBF\xBD"
-                       "end\"");
+    ASSERT_STR_EQ(out, "@bytes:6576696c016e616d65ff656e64");
+    free(out);
+
+    cbm_sb_init(&sb);
+    cbm_tree_cell_str(&sb, "@bytes:ff", true);
+    out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    ASSERT_STR_EQ(out, "@utf8:@bytes:ff");
     free(out);
 
     cbm_sb_init(&sb);
@@ -601,6 +614,353 @@ TEST(tree_cell_sanitizes_control_and_invalid_utf8) {
     PASS();
 }
 
+TEST(output_text_accepts_embedded_nul_as_valid_utf8) {
+    const char raw[] = {'a', '\0', 'b'};
+    char *encoded = NULL;
+    size_t encoded_len = 0;
+    ASSERT_TRUE(cbm_output_encode_text(raw, sizeof(raw), &encoded, &encoded_len));
+    ASSERT_NULL(encoded); /* U+0000 is valid UTF-8; the length-aware renderer escapes it. */
+    ASSERT_EQ(encoded_len, sizeof(raw));
+    free(encoded);
+    PASS();
+}
+
+TEST(json_to_tree_uses_header_once_rows_without_losing_metadata) {
+    const char *json =
+        "{\"projects\":[{\"name\":\"alpha\",\"nodes\":10},{\"name\":\"beta\",\"nodes\":20}],"
+        "\"total\":2,\"has_more\":false,\"nested\":{\"warning\":\"keep me\"}}";
+    char *tree = cbm_json_to_tree(json);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_STR_EQ(tree, "projects: 2  (cols: name nodes)\n"
+                        "  alpha 10\n"
+                        "  beta 20\n"
+                        "total: 2\n"
+                        "has_more: false\n"
+                        "nested:\n"
+                        "  warning: \"keep me\"\n");
+    free(tree);
+    PASS();
+}
+
+TEST(json_to_tree_keeps_multiline_source_readable) {
+    const char *json = "{\"source\":\"int main(void) {\\n\\treturn 0;\\n}\","
+                       "\"content\":\"# Decision\\n\\nKeep graph answers compact.\\n\"}";
+    char *tree = cbm_json_to_tree(json);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_STR_EQ(tree, "source: |-\n"
+                        "  int main(void) {\n"
+                        "  \treturn 0;\n"
+                        "  }\n"
+                        "content: |\n"
+                        "  # Decision\n"
+                        "  \n"
+                        "  Keep graph answers compact.\n");
+    ASSERT_NULL(strstr(tree, "\\n"));
+    free(tree);
+    PASS();
+}
+
+TEST(json_to_tree_quotes_dynamic_keys_without_line_injection) {
+    const char *json = "{\"bad\\nkey\":{\"colon:key\":1,\"\":2},"
+                       "\"rows\":[{\"col\\tname\":\"x\",\"close)\":\"y\"}]}";
+    char *tree = cbm_json_to_tree(json);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_STR_EQ(tree, "\"bad\\nkey\":\n"
+                        "  \"colon:key\": 1\n"
+                        "  \"\": 2\n"
+                        "rows: 1  (cols: \"col\\u0009name\" \"close)\")\n"
+                        "  x y\n");
+    free(tree);
+    PASS();
+}
+
+TEST(json_to_tree_preserves_embedded_nul_keys_values_and_table_cells) {
+    const char *json = "{\"a\\u0000b\":\"x\\u0000y\",\"multiline\":\"x\\u0000\\ny\","
+                       "\"reserved\":\"@bytes:x\\u0000y\","
+                       "\"rows\":[{\"k\\u0000x\":\"v\\u0000one\",\"k\\u0000y\":\"left\"},"
+                       "{\"k\\u0000x\":\"two\",\"k\\u0000y\":\"q\\u0000right\"}]}";
+    char *tree = cbm_json_to_tree(json);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_STR_EQ(tree, "\"a\\u0000b\": \"x\\u0000y\"\n"
+                        "multiline: \"x\\u0000\\ny\"\n"
+                        "reserved: \"@utf8:@bytes:x\\u0000y\"\n"
+                        "rows: 2  (cols: \"k\\u0000x\" \"k\\u0000y\")\n"
+                        "  \"v\\u0000one\" left\n"
+                        "  two \"q\\u0000right\"\n");
+    free(tree);
+    PASS();
+}
+
+/* Decode the intentionally tiny one-column subset used by the prefix-directory
+ * round-trip test. Its values need no tree quoting, so any mismatch is an
+ * encoder/reference bug rather than a second parser implementation. */
+static bool profiled_single_column_round_trips(const char *output, const char *key,
+                                               const char *const *expected, int expected_count) {
+    char refs_header[128];
+    char rows_header[128];
+    snprintf(refs_header, sizeof(refs_header), "%s_refs:", key);
+    snprintf(rows_header, sizeof(rows_header), "\n%s:", key);
+    const char *refs = strstr(output, refs_header);
+    const char *rows = refs ? strstr(refs, rows_header) : NULL;
+    if (!refs || !rows) {
+        return false;
+    }
+    const char *line = strchr(refs, '\n');
+    if (!line) {
+        return false;
+    }
+    line++;
+    char *prefixes[16] = {0};
+    while (line < rows && line[0] == ' ' && line[1] == ' ') {
+        char *end = NULL;
+        long id = strtol(line + 2, &end, 10);
+        if (id < 0 || id >= 16 || !end || *end != ' ') {
+            goto fail;
+        }
+        const char *prefix = end + 1;
+        const char *newline = strchr(prefix, '\n');
+        if (!newline || newline > rows) {
+            goto fail;
+        }
+        prefixes[id] = cbm_strndup(prefix, (size_t)(newline - prefix));
+        if (!prefixes[id]) {
+            goto fail;
+        }
+        line = newline + 1;
+    }
+    line = strchr(rows + 1, '\n');
+    if (!line) {
+        goto fail;
+    }
+    line++;
+    for (int row = 0; row < expected_count; row++) {
+        if (line[0] != ' ' || line[1] != ' ') {
+            goto fail;
+        }
+        const char *value = line + 2;
+        const char *newline = strchr(value, '\n');
+        if (!newline) {
+            goto fail;
+        }
+        char *decoded = NULL;
+        if (value[0] == '@' && isdigit((unsigned char)value[1])) {
+            char *ref_end = NULL;
+            long id = strtol(value + 1, &ref_end, 10);
+            if (id < 0 || id >= 16 || !ref_end || *ref_end != '+' || !prefixes[id]) {
+                goto fail;
+            }
+            size_t prefix_len = strlen(prefixes[id]);
+            size_t suffix_len = (size_t)(newline - (ref_end + 1));
+            decoded = malloc(prefix_len + suffix_len + 1U);
+            if (!decoded) {
+                goto fail;
+            }
+            memcpy(decoded, prefixes[id], prefix_len);
+            memcpy(decoded + prefix_len, ref_end + 1, suffix_len);
+            decoded[prefix_len + suffix_len] = '\0';
+        } else {
+            decoded = cbm_strndup(value, (size_t)(newline - value));
+        }
+        bool equal = decoded && strcmp(decoded, expected[row]) == 0;
+        free(decoded);
+        if (!equal) {
+            goto fail;
+        }
+        line = newline + 1;
+    }
+    for (int i = 0; i < 16; i++) {
+        free(prefixes[i]);
+    }
+    return true;
+
+fail:
+    for (int i = 0; i < 16; i++) {
+        free(prefixes[i]);
+    }
+    return false;
+}
+
+TEST(tree_table_uses_prefix_dictionary_only_when_it_materially_wins) {
+    enum { ROWS = 20, COLS = 3 };
+    const char *cols[COLS] = {"qn", "file", "literal"};
+    const char *cells[ROWS * COLS];
+    char qns[ROWS][128];
+    char literals[ROWS][64];
+    for (int i = 0; i < ROWS; i++) {
+        snprintf(qns[i], sizeof(qns[i]), "cbm-lean-output.tests.test_c_lsp.function_%02d", i);
+        snprintf(literals[i], sizeof(literals[i]), "@0+literal_%02d", i);
+        cells[i * COLS] = qns[i];
+        cells[i * COLS + 1] = "tests/test_c_lsp.c";
+        cells[i * COLS + 2] = literals[i];
+    }
+    cbm_sb_t sb;
+    cbm_sb_init(&sb);
+    const bool prefix_cols[COLS] = {true, true, false};
+    cbm_tree_table_rows_profiled(&sb, "rows", ROWS, cols, COLS, cells, NULL, prefix_cols);
+    char *out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    ASSERT_NOT_NULL(strstr(out, "rows_refs:"));
+    ASSERT_NOT_NULL(strstr(out, "rows_ref_rule: @N+suffix=prefix+suffix"));
+    ASSERT_NOT_NULL(strstr(out, "cbm-lean-output.tests.test_c_lsp."));
+    ASSERT_NOT_NULL(strstr(out, "@0+function_00"));
+    ASSERT_NOT_NULL(strstr(out, "tests/test_c_lsp.c"));
+    ASSERT_NOT_NULL(strstr(out, "@1+"));               /* exact repeated value: empty suffix */
+    ASSERT_NOT_NULL(strstr(out, "\"@0+literal_00\"")); /* data, not a ref */
+    ASSERT_LT((int)strlen(out), 1200);
+    size_t compact_len = strlen(out);
+    free(out);
+
+    cbm_sb_init(&sb);
+    cbm_tree_table_rows_typed(&sb, "rows", ROWS, cols, COLS, cells, NULL);
+    char *direct = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(direct);
+    ASSERT_TRUE(compact_len + 64U <= strlen(direct));
+    ASSERT_TRUE(compact_len * 100U <= strlen(direct) * 85U);
+    free(direct);
+
+    const char *typed_cols[COLS] = {"path", "type", "children"};
+    const bool string_cols[COLS] = {true, true, false};
+    const bool typed_prefix_cols[COLS] = {true, false, false};
+    const char *typed_cells[ROWS * COLS];
+    char paths[ROWS][128];
+    char children[ROWS][8];
+    for (int i = 0; i < ROWS; i++) {
+        snprintf(paths[i], sizeof(paths[i]), "services/orders/internal/handlers/file_%02d.go", i);
+        snprintf(children[i], sizeof(children[i]), "%d", i + 1);
+        typed_cells[i * COLS] = paths[i];
+        typed_cells[i * COLS + 1] = "file";
+        typed_cells[i * COLS + 2] = children[i];
+    }
+    cbm_sb_init(&sb);
+    cbm_tree_table_rows_profiled(&sb, "file_tree", ROWS, typed_cols, COLS, typed_cells, string_cols,
+                                 typed_prefix_cols);
+    out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    ASSERT_NOT_NULL(strstr(out, "file_tree_refs:"));
+    ASSERT_NOT_NULL(strstr(out, "services/orders/internal/handlers/"));
+    ASSERT_NOT_NULL(strstr(out, "@0+file_00.go file 1"));
+    ASSERT_NULL(strstr(out, "file \"1\""));
+    free(out);
+
+    const char *small_cols[] = {"qn", "file"};
+    const char *small_cells[] = {"alpha.long.qualified.Name", "src/a.c", "beta.long.qualified.Name",
+                                 "src/b.c"};
+    cbm_sb_init(&sb);
+    cbm_tree_table_rows(&sb, "rows", 2, small_cols, 2, small_cells);
+    out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    ASSERT_NULL(strstr(out, "rows_refs:"));
+    ASSERT_NOT_NULL(strstr(out, "alpha.long.qualified.Name src/a.c"));
+    free(out);
+
+    /* Arbitrary string columns stay literal unless the caller explicitly marks
+     * them as semantic paths/QNs. */
+    cbm_sb_init(&sb);
+    cbm_tree_table_rows(&sb, "rows", ROWS, cols, COLS, cells);
+    out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    ASSERT_NULL(strstr(out, "rows_refs:"));
+    ASSERT_NOT_NULL(strstr(out, "cbm-lean-output.tests.test_c_lsp.function_00"));
+    free(out);
+
+    /* Decode every emitted reference across Unix, Windows, C++ and UTF-8
+     * semantic boundaries, including an exact repeat with an empty suffix. */
+    enum { ROUNDTRIP_ROWS = 36 };
+    char roundtrip_values[ROUNDTRIP_ROWS][128];
+    const char *roundtrip_cells[ROUNDTRIP_ROWS];
+    for (int i = 0; i < ROUNDTRIP_ROWS; i++) {
+        if (i < 8) {
+            snprintf(roundtrip_values[i], sizeof(roundtrip_values[i]),
+                     "services/orders/internal/handlers/file_%02d.go", i);
+        } else if (i < 16) {
+            snprintf(roundtrip_values[i], sizeof(roundtrip_values[i]),
+                     "acme::orders::handlers::function_%02d", i);
+        } else if (i < 24) {
+            snprintf(roundtrip_values[i], sizeof(roundtrip_values[i]),
+                     "C:\\workspace\\orders\\handlers\\file_%02d.cpp", i);
+        } else if (i < 32) {
+            snprintf(roundtrip_values[i], sizeof(roundtrip_values[i]),
+                     "paket.über.modul.handler_%02d", i);
+        } else {
+            snprintf(roundtrip_values[i], sizeof(roundtrip_values[i]),
+                     "services/orders/shared/exact/value.go");
+        }
+        roundtrip_cells[i] = roundtrip_values[i];
+    }
+    const char *roundtrip_cols[] = {"path"};
+    const bool roundtrip_string_cols[] = {true};
+    const bool roundtrip_prefix_cols[] = {true};
+    cbm_sb_init(&sb);
+    cbm_tree_table_rows_profiled(&sb, "roundtrip", ROUNDTRIP_ROWS, roundtrip_cols, 1,
+                                 roundtrip_cells, roundtrip_string_cols, roundtrip_prefix_cols);
+    out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    ASSERT_NOT_NULL(strstr(out, "roundtrip_refs:"));
+    ASSERT_TRUE(
+        profiled_single_column_round_trips(out, "roundtrip", roundtrip_cells, ROUNDTRIP_ROWS));
+    free(out);
+
+    /* A declaration that itself resembles a ref is quoted and remains a
+     * literal: directory expansion applies only to the sibling data table. */
+    char refish_values[ROWS][96];
+    const char *refish_cells[ROWS];
+    for (int i = 0; i < ROWS; i++) {
+        snprintf(refish_values[i], sizeof(refish_values[i]), "@0+namespace.component.member_%02d",
+                 i);
+        refish_cells[i] = refish_values[i];
+    }
+    cbm_sb_init(&sb);
+    cbm_tree_table_rows_profiled(&sb, "refish", ROWS, roundtrip_cols, 1, refish_cells,
+                                 roundtrip_string_cols, roundtrip_prefix_cols);
+    out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    ASSERT_NOT_NULL(strstr(out, "\"@0+namespace.component.\""));
+    ASSERT_NOT_NULL(strstr(out, "  @0+member_00\n"));
+    free(out);
+
+    for (int i = 0; i < ROWS; i++) {
+        snprintf(refish_values[i], sizeof(refish_values[i]), "123456789012.member_%02d", i);
+    }
+    cbm_sb_init(&sb);
+    cbm_tree_table_rows_profiled(&sb, "numeric_prefix", ROWS, roundtrip_cols, 1, refish_cells,
+                                 roundtrip_string_cols, roundtrip_prefix_cols);
+    out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    /* The lexical proxy may conservatively decline a numeric-prefix directory
+     * even though cl100k/o200k save four tokens here. Either representation is
+     * complete; if compacted, the numeric declaration must stay quoted. */
+    if (strstr(out, "numeric_prefix_refs:")) {
+        ASSERT_NOT_NULL(strstr(out, "\"123456789012.\""));
+        ASSERT_NOT_NULL(strstr(out, "  @0+member_00\n"));
+    } else {
+        ASSERT_NOT_NULL(strstr(out, "123456789012.member_00"));
+    }
+    free(out);
+
+    /* A long prefix is not necessarily token-expensive. Both cl100k and
+     * o200k encode `establishment.handler_0000` one token more cheaply than
+     * `@0+handler_0000`; a byte-only winner therefore regresses the actual
+     * context budget at scale. The model-neutral token-shape gate must keep
+     * this table direct even though a directory saves more than 15% of bytes. */
+    enum { TOKEN_CHEAP_ROWS = 200 };
+    char token_cheap_values[TOKEN_CHEAP_ROWS][64];
+    const char *token_cheap_cells[TOKEN_CHEAP_ROWS];
+    for (int i = 0; i < TOKEN_CHEAP_ROWS; i++) {
+        snprintf(token_cheap_values[i], sizeof(token_cheap_values[i]), "establishment.handler_%04d",
+                 i);
+        token_cheap_cells[i] = token_cheap_values[i];
+    }
+    cbm_sb_init(&sb);
+    cbm_tree_table_rows_profiled(&sb, "token_cheap", TOKEN_CHEAP_ROWS, roundtrip_cols, 1,
+                                 token_cheap_cells, roundtrip_string_cols, roundtrip_prefix_cols);
+    out = cbm_sb_finish(&sb);
+    ASSERT_NOT_NULL(out);
+    ASSERT_NULL(strstr(out, "token_cheap_refs:"));
+    ASSERT_NOT_NULL(strstr(out, "establishment.handler_0000"));
+    free(out);
+    PASS();
+}
+
 /* ══════════════════════════════════════════════════════════════════
  *  JSON-RPC PARSING
  * ══════════════════════════════════════════════════════════════════ */
@@ -822,9 +1182,9 @@ TEST(mcp_tools_help_list_matches_registry) {
 TEST(mcp_tools_list_latest_metadata) {
     char *json = cbm_mcp_tools_list();
     ASSERT_NOT_NULL(json);
-    ASSERT_NOT_NULL(strstr(json, "\"title\":\"Search graph\""));
-    ASSERT_NOT_NULL(strstr(json, "\"title\":\"Index repository\""));
-    ASSERT_NOT_NULL(strstr(json, "\"title\":\"Check index coverage\""));
+    /* MCP tool titles are optional; name is the specified display fallback.
+     * Avoid paying for space-cased duplicates on every discovery response. */
+    ASSERT_NULL(strstr(json, "\"title\":"));
     /* No tool may declare an outputSchema. The blanket permissive schema
      * ({"type":"object","additionalProperties":true}) carried zero information
      * for clients, but its presence made spec-compliant clients read
@@ -836,13 +1196,109 @@ TEST(mcp_tools_list_latest_metadata) {
      * relationships used for call/reference/type centrality, not every edge
      * family (for example DEFINES or CONTAINS_FILE). Keep the public contract
      * aligned with the store query. */
-    ASSERT_NOT_NULL(strstr(json, "in/out = selected degree across CALLS, USAGE, CALL_REFERENCE, "
-                                 "INHERITS, and IMPLEMENTS"));
+    ASSERT_NOT_NULL(strstr(json, "Find symbols via BM25 query, regex name/qn filters, or "
+                                 "semantic_query"));
+    ASSERT_NOT_NULL(strstr(json, "Rows keep qn/file/lines and in/out over CALLS"));
+    ASSERT_NOT_NULL(strstr(json, "USAGE"));
+    ASSERT_NOT_NULL(strstr(json, "CALL_REFERENCE"));
+    ASSERT_NOT_NULL(strstr(json, "INHERITS"));
+    ASSERT_NOT_NULL(strstr(json, "IMPLEMENTS"));
     ASSERT_NULL(strstr(json, "TOTAL degree across ALL edge types"));
     free(json);
     PASS();
 }
 
+TEST(mcp_discovery_defaults_match_runtime_contract) {
+    const char *search_schema = cbm_mcp_tool_input_schema("search_graph");
+    ASSERT_NOT_NULL(search_schema);
+    yyjson_doc *doc = yyjson_read(search_schema, strlen(search_schema), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *props = yyjson_obj_get(yyjson_doc_get_root(doc), "properties");
+    ASSERT_NOT_NULL(props);
+    yyjson_val *format = yyjson_obj_get(props, "format");
+    yyjson_val *detail = yyjson_obj_get(props, "detail");
+    ASSERT_NOT_NULL(format);
+    ASSERT_NOT_NULL(detail);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(format, "default")), "tree");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(detail, "default")), "default");
+    yyjson_doc_free(doc);
+
+    const char *detect_schema = cbm_mcp_tool_input_schema("detect_changes");
+    ASSERT_NOT_NULL(detect_schema);
+    doc = yyjson_read(detect_schema, strlen(detect_schema), 0);
+    ASSERT_NOT_NULL(doc);
+    props = yyjson_obj_get(yyjson_doc_get_root(doc), "properties");
+    ASSERT_NOT_NULL(props);
+    yyjson_val *scope = yyjson_obj_get(props, "scope");
+    ASSERT_NOT_NULL(scope);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(scope, "default")), "impact");
+    yyjson_doc_free(doc);
+
+    /* search_graph's omitted values and the newly-declared defaults must be
+     * behaviorally identical. */
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "discovery-default-contract";
+    ASSERT_EQ(cbm_store_upsert_project(store, project, cbm_tmpdir()), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
+    cbm_node_t node = {.project = project,
+                       .label = "Function",
+                       .name = "default_contract",
+                       .qualified_name = "fixture.default_contract",
+                       .file_path = "src/default.c",
+                       .start_line = 1,
+                       .end_line = 2};
+    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    char *implicit = cbm_mcp_handle_tool(
+        srv, "search_graph",
+        "{\"project\":\"discovery-default-contract\",\"name_pattern\":\"default_contract\"}");
+    char *explicit_defaults = cbm_mcp_handle_tool(
+        srv, "search_graph",
+        "{\"project\":\"discovery-default-contract\",\"name_pattern\":\"default_contract\","
+        "\"format\":\"tree\",\"detail\":\"default\"}");
+    ASSERT_NOT_NULL(implicit);
+    ASSERT_NOT_NULL(explicit_defaults);
+    ASSERT_STR_EQ(implicit, explicit_defaults);
+    free(implicit);
+    free(explicit_defaults);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(mcp_metadata_byte_budget) {
+    /* Tool metadata is paid on discovery before any graph answer is returned.
+     * Byte ceilings are deterministic across tokenizers and force deliberate
+     * review when a schema or new tool grows the model-visible baseline. */
+    char *init = cbm_mcp_initialize_response(NULL);
+    ASSERT_NOT_NULL(init);
+    ASSERT_LT((int)strlen(init), 512);
+    free(init);
+
+    char *json = cbm_mcp_tools_list();
+    ASSERT_NOT_NULL(json);
+    ASSERT_LT((int)strlen(json), 15 * 1024);
+
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *tools = yyjson_obj_get(yyjson_doc_get_root(doc), "tools");
+    ASSERT_NOT_NULL(tools);
+    ASSERT_EQ((int)yyjson_arr_size(tools), cbm_mcp_tool_count());
+    size_t idx;
+    size_t max;
+    yyjson_val *tool;
+    yyjson_arr_foreach(tools, idx, max, tool) {
+        char *serialized = yyjson_val_write(tool, 0, NULL);
+        ASSERT_NOT_NULL(serialized);
+        ASSERT_LT((int)strlen(serialized), 3200);
+        free(serialized);
+    }
+    yyjson_doc_free(doc);
+    free(json);
+    PASS();
+}
+
 TEST(mcp_tools_have_behavior_annotations) {
     struct {
         const char *name;
@@ -1123,6 +1579,39 @@ TEST(mcp_text_result_omits_structured_content_for_plain_text) {
     PASS();
 }
 
+TEST(mcp_text_result_reversibly_encodes_invalid_utf8_as_standard_json) {
+    const char invalid[] = {'n', 'a', 'm', 'e', (char)0xff, '\0'};
+    char *json = cbm_mcp_text_result(invalid, false);
+    ASSERT_NOT_NULL(json);
+
+    /* Strict parsing is the interoperability contract: never rely on
+     * YYJSON_WRITE_ALLOW_INVALID_UNICODE's non-standard byte passthrough. */
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *content = yyjson_obj_get(root, "content");
+    yyjson_val *item = yyjson_arr_get_first(content);
+    yyjson_val *text_value = item ? yyjson_obj_get(item, "text") : NULL;
+    ASSERT_TRUE(yyjson_is_str(text_value));
+    ASSERT_STR_EQ(yyjson_get_str(text_value), "@bytes:6e616d65ff");
+    yyjson_doc_free(doc);
+    free(json);
+
+    json = cbm_mcp_text_result("@bytes:6e616d65ff", false);
+    ASSERT_NOT_NULL(json);
+    doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    content = yyjson_obj_get(root, "content");
+    item = yyjson_arr_get_first(content);
+    text_value = item ? yyjson_obj_get(item, "text") : NULL;
+    ASSERT_TRUE(yyjson_is_str(text_value));
+    ASSERT_STR_EQ(yyjson_get_str(text_value), "@utf8:@bytes:6e616d65ff");
+    yyjson_doc_free(doc);
+    free(json);
+    PASS();
+}
+
 TEST(mcp_cancel_matches_request_id) {
     ASSERT_TRUE(cbm_mcp_cancel_request_matches("{\"requestId\":7}", 7, NULL));
     ASSERT_FALSE(cbm_mcp_cancel_request_matches("{\"requestId\":8}", 7, NULL));
@@ -1637,6 +2126,112 @@ static cbm_mcp_server_t *setup_snippet_server(char *tmp_dir, size_t tmp_sz);
 static void cleanup_snippet_dir(const char *tmp_dir);
 static char *extract_text_content(const char *mcp_result);
 
+/* A singleton dotless QN is smaller as a direct row than as a one-entry group.
+ * The adaptive tree must preserve it byte-for-byte without paying a grouping
+ * rule; structured JSON retains its stable grouped machine shape. */
+TEST(tool_search_graph_grouped_dotless_qn_round_trips) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-dotless-qn";
+    const char *qualified_name = "__route__ANY__/api/adr";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/search-dotless-qn"), CBM_STORE_OK);
+    cbm_node_t route = {.project = project,
+                        .label = "Route",
+                        .name = "dotless_route",
+                        .qualified_name = qualified_name,
+                        .file_path = "src/routes.c",
+                        .start_line = 7,
+                        .end_line = 7};
+    ASSERT_GT(cbm_store_upsert_node(store, &route), 0);
+
+    const char *tree_args =
+        "{\"project\":\"search-dotless-qn\",\"name_pattern\":\"dotless_route\"}";
+    char *response = cbm_mcp_handle_tool(srv, "search_graph", tree_args);
+    char *tree = extract_text_content(response);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NULL(strstr(tree, "group prefix"));
+    ASSERT_NOT_NULL(strstr(tree, "(cols: qn label file lines in out)"));
+    ASSERT_NOT_NULL(strstr(tree, "__route__ANY__/api/adr Route src/routes.c 7-7"));
+    ASSERT_NULL(strstr(tree, ".__route__ANY__/api/adr"));
+    free(tree);
+    free(response);
+
+    response =
+        cbm_mcp_handle_tool(srv, "search_graph",
+                            "{\"project\":\"search-dotless-qn\",\"name_pattern\":\"dotless_route\","
+                            "\"format\":\"json\"}");
+    char *json = extract_text_content(response);
+    ASSERT_NOT_NULL(json);
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "qn_rule")),
+                  "qn = qn_prefix == \"\" ? name : qn_prefix + \".\" + name");
+    yyjson_val *groups = yyjson_obj_get(root, "groups");
+    ASSERT_NOT_NULL(groups);
+    ASSERT_EQ(yyjson_arr_size(groups), 1);
+    yyjson_val *group = yyjson_arr_get_first(groups);
+    const char *prefix = yyjson_get_str(yyjson_obj_get(group, "qn_prefix"));
+    ASSERT_NOT_NULL(prefix);
+    ASSERT_STR_EQ(prefix, "");
+    yyjson_val *rows = yyjson_obj_get(group, "rows");
+    ASSERT_NOT_NULL(rows);
+    ASSERT_EQ(yyjson_arr_size(rows), 1);
+    const char *name = yyjson_get_str(yyjson_arr_get(yyjson_arr_get_first(rows), 0));
+    ASSERT_NOT_NULL(name);
+    char reconstructed[128];
+    if (prefix[0]) {
+        snprintf(reconstructed, sizeof(reconstructed), "%s.%s", prefix, name);
+    } else {
+        snprintf(reconstructed, sizeof(reconstructed), "%s", name);
+    }
+    ASSERT_STR_EQ(reconstructed, qualified_name);
+
+    yyjson_doc_free(doc);
+    free(json);
+    free(response);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+static yyjson_val *trace_grouped_row_named(yyjson_val *leg, const char *name,
+                                           const char **prefix_out) {
+    if (prefix_out) {
+        *prefix_out = NULL;
+    }
+    yyjson_val *groups = leg ? yyjson_obj_get(leg, "groups") : NULL;
+    if (!groups || !yyjson_is_arr(groups)) {
+        return NULL;
+    }
+    size_t group_index;
+    size_t group_max;
+    yyjson_val *group;
+    yyjson_arr_foreach(groups, group_index, group_max, group) {
+        yyjson_val *rows = yyjson_obj_get(group, "rows");
+        if (!rows || !yyjson_is_arr(rows)) {
+            continue;
+        }
+        size_t row_index;
+        size_t row_max;
+        yyjson_val *row;
+        yyjson_arr_foreach(rows, row_index, row_max, row) {
+            yyjson_val *row_name = yyjson_is_arr(row) ? yyjson_arr_get(row, 0) : NULL;
+            if (!row_name || !yyjson_is_str(row_name) ||
+                strcmp(yyjson_get_str(row_name), name) != 0) {
+                continue;
+            }
+            if (prefix_out) {
+                *prefix_out = yyjson_get_str(yyjson_obj_get(group, "qn_prefix"));
+            }
+            return row;
+        }
+    }
+    return NULL;
+}
+
 /* callers_total/callees_total must count what the caller can enumerate: with
  * include_tests=false (default) test-file rows are hidden from the table, so
  * the totals must apply the same filter — a raw visited_count overstated the
@@ -1720,6 +2315,12 @@ TEST(tool_get_architecture_cycles_detects_scc) {
     cbm_store_upsert_project(st, proj, "/tmp/cyc");
 
     const char *names[5] = {"A", "B", "C", "D", "E"};
+    enum { LONG_CYCLE_QN_BYTES = 2500 };
+    char *long_cycle_qn = malloc(LONG_CYCLE_QN_BYTES + 16U);
+    ASSERT_NOT_NULL(long_cycle_qn);
+    memcpy(long_cycle_qn, "cycproj.m.", 10U);
+    memset(long_cycle_qn + 10U, 'x', LONG_CYCLE_QN_BYTES);
+    memcpy(long_cycle_qn + 10U + LONG_CYCLE_QN_BYTES, ".A", 3U);
     int64_t id[5];
     for (int i = 0; i < 5; i++) {
         char qn[32];
@@ -1727,7 +2328,7 @@ TEST(tool_get_architecture_cycles_detects_scc) {
         cbm_node_t n = {.project = proj,
                         .label = "Function",
                         .name = names[i],
-                        .qualified_name = qn,
+                        .qualified_name = i == 0 ? long_cycle_qn : qn,
                         .file_path = "m.c",
                         .start_line = i + 1,
                         .end_line = i + 2};
@@ -1754,13 +2355,39 @@ TEST(tool_get_architecture_cycles_detects_scc) {
     char *inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
     ASSERT_NOT_NULL(strstr(inner, "cycles: 1")); /* exactly one SCC of size>1 */
-    ASSERT_NOT_NULL(strstr(inner, "cycproj.m.A"));
+    ASSERT_NOT_NULL(strstr(inner, long_cycle_qn));
     ASSERT_NOT_NULL(strstr(inner, "cycproj.m.B"));
     ASSERT_NOT_NULL(strstr(inner, "cycproj.m.C"));
     ASSERT_NULL(strstr(inner, "cycproj.m.D")); /* acyclic node not in any cycle */
     free(inner);
     free(resp);
 
+    resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":711,\"method\":\"tools/call\",\"params\":{"
+             "\"name\":\"get_architecture\",\"arguments\":{\"project\":\"cycproj\","
+             "\"aspects\":[\"cycles\"],\"format\":\"json\"}}}");
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *cycle_doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(cycle_doc);
+    yyjson_val *cycles = yyjson_obj_get(yyjson_doc_get_root(cycle_doc), "cycles");
+    yyjson_val *cycle = yyjson_arr_get_first(cycles);
+    yyjson_val *members = cycle ? yyjson_obj_get(cycle, "members") : NULL;
+    bool found_long_qn = false;
+    size_t member_index, member_max;
+    yyjson_val *member;
+    yyjson_arr_foreach(members, member_index, member_max, member) {
+        const char *value = yyjson_get_str(member);
+        if (value && strcmp(value, long_cycle_qn) == 0) {
+            found_long_qn = true;
+        }
+    }
+    ASSERT_TRUE(found_long_qn);
+    yyjson_doc_free(cycle_doc);
+    free(inner);
+    free(resp);
+
     /* default call (no aspects) must NOT run the scan. */
     resp = cbm_mcp_server_handle(
         srv, "{\"jsonrpc\":\"2.0\",\"id\":72,\"method\":\"tools/call\",\"params\":{"
@@ -1772,6 +2399,7 @@ TEST(tool_get_architecture_cycles_detects_scc) {
     free(inner);
     free(resp);
     cbm_mcp_server_free(srv);
+    free(long_cycle_qn);
     PASS();
 }
 
@@ -1821,10 +2449,43 @@ TEST(tool_get_code_snippet_clips_whole_file_node) {
     ASSERT_NOT_NULL(resp);
     char *inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "source_mode: outline"));
+    /* Container defaults carry the member outline, never raw whole-file source. */
+    ASSERT_TRUE(strlen(inner) < 4000);
+    ASSERT_NOT_NULL(strstr(inner, "end_line: 2000"));
+    ASSERT_NULL(strstr(inner, "source_truncated"));
+    ASSERT_NULL(strstr(inner, "next_start_line"));
+    ASSERT_NULL(strstr(inner, "line_0000"));
+    ASSERT_NULL(strstr(inner, "line_1999"));
+    free(inner);
+    free(resp);
+
+    /* Explicit full is the compatibility/detail opt-in: without an explicit
+     * token or line budget it reaches the established 500-line safety ceiling,
+     * rather than inheriting auto mode's lean 2.5k-token estimate. */
+    resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":72,\"method\":\"tools/call\",\"params\":{"
+             "\"name\":\"get_code_snippet\",\"arguments\":{\"project\":\"test-project\","
+             "\"qualified_name\":\"test-project.big\",\"source_mode\":\"full\","
+             "\"format\":\"json\"}}}");
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "line_0499"));
+    ASSERT_NULL(strstr(inner, "line_0500"));
+    ASSERT_NOT_NULL(strstr(inner, "\"next_start_line\":501"));
+    free(inner);
+    free(resp);
+
+    resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":71,\"method\":\"tools/call\",\"params\":{"
+             "\"name\":\"get_code_snippet\",\"arguments\":{\"project\":\"test-project\","
+             "\"qualified_name\":\"test-project.big\",\"source_mode\":\"full\","
+             "\"max_output_tokens\":10000,\"format\":\"json\"}}}");
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
     ASSERT_NOT_NULL(strstr(inner, "\"source_clipped\":true"));
-    /* The whole 2000-line file (~100KB) must NOT be in the response. */
-    ASSERT_TRUE(strlen(inner) < 60000);
-    /* The last line must be absent (clipped), the first present. */
     ASSERT_NOT_NULL(strstr(inner, "line_0000"));
     ASSERT_NULL(strstr(inner, "line_1999"));
     free(inner);
@@ -1834,31 +2495,196 @@ TEST(tool_get_code_snippet_clips_whole_file_node) {
     PASS();
 }
 
-/* EVERY tool, not just the one that was reported.
- *
- * The duplication was invisible per-tool: each result looked reasonable on its
- * own, and only measuring the wire showed half of it was redundant. A guard
- * pinned to query_graph would not have caught it in search_graph, and would not
- * catch it in whatever tool is added next. So this enumerates the tool table
- * itself — a new tool is covered the moment it is registered, with no test edit.
- *
- * The invariant, tightened by #1522: for a NON-error result whose payload is
- * not a JSON object, the envelope must carry NO structuredContent key — not the
- * payload a second time (#1375's duplication), and not an empty object either
- * (#1488's replacement, which spec-compliant clients rendered as the entire
- * result: "{}"). Object payloads keep their parsed structuredContent; errors
- * keep structuredContent.error — bounded, small, and the only machine-readable
- * form of a failure a client gets. */
-TEST(mcp_every_tool_result_is_duplication_free) {
+TEST(tool_get_code_snippet_omits_over_budget_whole_line) {
     char tmp[256];
-    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
-    ASSERT_NOT_NULL(srv);
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_snipwide_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    char src_path[512];
+    snprintf(src_path, sizeof(src_path), "%s/wide.c", tmp);
+    FILE *fp = fopen(src_path, "wb");
+    ASSERT_NOT_NULL(fp);
+    fputs("void wide(void) { /* TOKEN_NEEDLE ", fp);
+    for (int i = 0; i < 40000; i++) {
+        fputc('x', fp);
+    }
+    fputs(" */ }\n", fp);
+    fclose(fp);
 
-    int tools = cbm_mcp_tool_count();
-    ASSERT_TRUE(tools > 0); /* an empty table would assert nothing at all */
-    int checked = 0;
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "snippet-wide";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    cbm_node_t node = {.project = project,
+                       .label = "Function",
+                       .name = "wide",
+                       .qualified_name = "snippet-wide.wide",
+                       .file_path = "wide.c",
+                       .start_line = 1,
+                       .end_line = 1};
+    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
 
-    for (int i = 0; i < tools; i++) {
+    char *response = cbm_mcp_handle_tool(
+        srv, "get_code_snippet",
+        "{\"project\":\"snippet-wide\",\"qualified_name\":\"snippet-wide.wide\","
+        "\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_TRUE(strlen(inner) <= 2500U * 4U);
+    ASSERT_NOT_NULL(strstr(inner, "\"source_omitted\":true"));
+    ASSERT_NOT_NULL(strstr(inner, "\"truncation_reason\":\"output_budget\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"qualified_name\":\"snippet-wide.wide\""));
+    ASSERT_NOT_NULL(strstr(inner, "wide.c"));
+    ASSERT_NOT_NULL(strstr(inner, "\"start_line\":1"));
+    ASSERT_NOT_NULL(strstr(inner, "\"end_line\":1"));
+    ASSERT_NOT_NULL(strstr(inner, "\"original_end_line\":1"));
+    ASSERT_NOT_NULL(strstr(inner, "\"source_lines_returned\":0"));
+    ASSERT_NOT_NULL(strstr(inner, "\"continuation_requires_higher_budget\":true"));
+    ASSERT_NOT_NULL(strstr(inner, "raise max_output_tokens"));
+    ASSERT_NULL(strstr(inner, "next_start_line"));
+    ASSERT_NULL(strstr(inner, "cursor"));
+    ASSERT_NULL(strstr(inner, "TOKEN_NEEDLE"));
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "get_code_snippet",
+        "{\"project\":\"snippet-wide\",\"qualified_name\":\"snippet-wide.wide\"}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "source_omitted: true"));
+    ASSERT_NOT_NULL(strstr(inner, "qualified_name: snippet-wide.wide"));
+    ASSERT_NOT_NULL(strstr(inner, "wide.c"));
+    ASSERT_NOT_NULL(strstr(inner, "start_line: 1"));
+    ASSERT_NOT_NULL(strstr(inner, "end_line: 1"));
+    ASSERT_NOT_NULL(strstr(inner, "original_end_line: 1"));
+    ASSERT_NOT_NULL(strstr(inner, "source_lines_returned: 0"));
+    ASSERT_NOT_NULL(strstr(inner, "continuation_requires_higher_budget: true"));
+    ASSERT_NOT_NULL(strstr(inner, "raise max_output_tokens"));
+    ASSERT_NULL(strstr(inner, "next_start_line"));
+    ASSERT_NULL(strstr(inner, "cursor"));
+    ASSERT_NULL(strstr(inner, "TOKEN_NEEDLE"));
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "get_code_snippet",
+        "{\"project\":\"snippet-wide\",\"qualified_name\":\"snippet-wide.wide\","
+        "\"max_output_tokens\":20000,\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    const char *full_source = yyjson_get_str(yyjson_obj_get(root, "source"));
+    ASSERT_NOT_NULL(full_source);
+    ASSERT_EQ(strlen(full_source),
+              strlen("void wide(void) { /* TOKEN_NEEDLE ") + 40000U + strlen(" */ }\n"));
+    ASSERT_NOT_NULL(strstr(full_source, "TOKEN_NEEDLE"));
+    ASSERT_STR_EQ(full_source + strlen(full_source) - strlen(" */ }\n"), " */ }\n");
+    ASSERT_NULL(yyjson_obj_get(root, "source_omitted"));
+    ASSERT_NULL(yyjson_obj_get(root, "continuation_requires_higher_budget"));
+    yyjson_doc_free(doc);
+
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    cbm_unlink(src_path);
+    cbm_rmdir(tmp);
+    PASS();
+}
+
+TEST(tool_get_code_snippet_pages_outline_rows_to_exact_budget) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_snipoutline_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    char src_path[512];
+    snprintf(src_path, sizeof(src_path), "%s/module.py", tmp);
+    FILE *fp = fopen(src_path, "wb");
+    ASSERT_NOT_NULL(fp);
+    for (int i = 0; i < 400; i++) {
+        fprintf(fp, "# line %d\n", i + 1);
+    }
+    fclose(fp);
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "snippet-outline";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    cbm_node_t module = {.project = project,
+                         .label = "Module",
+                         .name = "module",
+                         .qualified_name = "snippet-outline.very.long.package.module",
+                         .file_path = "module.py",
+                         .start_line = 1,
+                         .end_line = 400};
+    ASSERT_GT(cbm_store_upsert_node(store, &module), 0);
+    for (int i = 0; i < 80; i++) {
+        char name[64];
+        char qn[512];
+        snprintf(name, sizeof(name), "member_%02d", i);
+        snprintf(qn, sizeof(qn),
+                 "snippet-outline.very.long.package.module.subsystem.component.member_%02d", i);
+        cbm_node_t member = {.project = project,
+                             .label = "Function",
+                             .name = name,
+                             .qualified_name = qn,
+                             .file_path = "module.py",
+                             .start_line = i * 4 + 2,
+                             .end_line = i * 4 + 4};
+        ASSERT_GT(cbm_store_upsert_node(store, &member), 0);
+    }
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "get_code_snippet",
+                            "{\"project\":\"snippet-outline\","
+                            "\"qualified_name\":\"snippet-outline.very.long.package.module\","
+                            "\"max_output_tokens\":128,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_TRUE(strlen(inner) <= 128U * 4U);
+    ASSERT_NOT_NULL(strstr(inner, "snippet-outline.very.long.package.module"));
+    ASSERT_NOT_NULL(strstr(inner, "\"source_mode\":\"outline\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"members_has_more\":true"));
+    ASSERT_NOT_NULL(strstr(inner, "\"next_member_offset\":"));
+    ASSERT_NOT_NULL(strstr(inner, "\"truncation_reason\":\"output_budget\""));
+
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    cbm_unlink(src_path);
+    cbm_rmdir(tmp);
+    PASS();
+}
+
+/* EVERY tool, not just the one that was reported.
+ *
+ * The duplication was invisible per-tool: each result looked reasonable on its
+ * own, and only measuring the wire showed half of it was redundant. A guard
+ * pinned to query_graph would not have caught it in search_graph, and would not
+ * catch it in whatever tool is added next. So this enumerates the tool table
+ * itself — a new tool is covered the moment it is registered, with no test edit.
+ *
+ * The invariant, tightened by #1522: for a NON-error result whose payload is
+ * not a JSON object, the envelope must carry NO structuredContent key — not the
+ * payload a second time (#1375's duplication), and not an empty object either
+ * (#1488's replacement, which spec-compliant clients rendered as the entire
+ * result: "{}"). Object payloads keep their parsed structuredContent; errors
+ * keep structuredContent.error — bounded, small, and the only machine-readable
+ * form of a failure a client gets. */
+TEST(mcp_every_tool_result_is_duplication_free) {
+    char tmp[256];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+
+    int tools = cbm_mcp_tool_count();
+    ASSERT_TRUE(tools > 0); /* an empty table would assert nothing at all */
+    int checked = 0;
+
+    for (int i = 0; i < tools; i++) {
         const char *name = cbm_mcp_tool_name(i);
         ASSERT_NOT_NULL(name);
         /* Minimal args: most tools error out, which is fine — an error envelope
@@ -1946,7 +2772,7 @@ TEST(tool_search_graph_includes_node_properties) {
     char *inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
     ASSERT_NOT_NULL(strstr(inner, "results:")); /* TOON table header */
-    ASSERT_NOT_NULL(strstr(inner, "(rows: name label lines in out;"));
+    ASSERT_NOT_NULL(strstr(inner, "(cols: qn label file lines in out)"));
     ASSERT_NOT_NULL(strstr(inner, "HandleRequest"));
     ASSERT_NULL(strstr(inner, "func HandleRequest")); /* signature not spilled */
     ASSERT_NULL(strstr(inner, "is_exported"));
@@ -1995,6 +2821,87 @@ TEST(tool_search_graph_includes_node_properties) {
     PASS();
 }
 
+TEST(tool_index_status_keeps_authoritative_ignored_total_when_rows_are_sampled) {
+    char tmp[256];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+
+    cbm_coverage_row_t row = {
+        .rel_path = "generated/ignored-0000.js", .kind = "not_indexed_file", .detail = "gitignore"};
+    cbm_project_t project = {0};
+    ASSERT_EQ(cbm_store_get_project(store, "test-project", &project), CBM_STORE_OK);
+    ASSERT_NOT_NULL(project.indexed_at);
+    cbm_coverage_meta_t meta = {.generation = project.indexed_at,
+                                .index_mode = "fast",
+                                .recorded_at = "2026-08-12T00:00:00Z",
+                                .recording_status = "truncated",
+                                .ignored_files_stored = 1,
+                                .ignored_files_total = 2500,
+                                .coverage_version = 1,
+                                .hash_records_complete = true};
+    ASSERT_EQ(cbm_store_coverage_replace_ex(store, "test-project", &row, 1, &meta), CBM_STORE_OK);
+
+    char *response = cbm_mcp_handle_tool(srv, "index_status",
+                                         "{\"project\":\"test-project\",\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *not_indexed = yyjson_obj_get(yyjson_doc_get_root(doc), "not_indexed");
+    ASSERT_NOT_NULL(not_indexed);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(not_indexed, "files_count")), 2500);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(not_indexed, "files_omitted")), 2500);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(not_indexed, "truncated")));
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(not_indexed, "files")), 0);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "index_status",
+        "{\"project\":\"test-project\",\"diagnostics\":\"full\",\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    not_indexed = yyjson_obj_get(yyjson_doc_get_root(doc), "not_indexed");
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(not_indexed, "files_count")), 2500);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(not_indexed, "files_omitted")), 2499);
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(not_indexed, "files")), 1);
+    ASSERT_NOT_NULL(strstr(inner, "generated/ignored-0000.js"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* A total from another index generation is diagnostic history, not the
+     * exact count for the current graph. Keep the recorded row count and mark
+     * its relation unknown instead of presenting stale metadata as truth. */
+    meta.generation = "stale-generation";
+    meta.ignored_files_total = 4000;
+    ASSERT_EQ(cbm_store_coverage_replace_ex(store, "test-project", &row, 1, &meta), CBM_STORE_OK);
+    response = cbm_mcp_handle_tool(srv, "index_status",
+                                   "{\"project\":\"test-project\",\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    not_indexed = yyjson_obj_get(yyjson_doc_get_root(doc), "not_indexed");
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(not_indexed, "files_count")), 1);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(not_indexed, "files_count_relation")), "gte");
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(not_indexed, "files_omitted")), 1);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    cbm_project_free_fields(&project);
+
+    cbm_mcp_server_free(srv);
+    cleanup_snippet_dir(tmp);
+    PASS();
+}
+
 TEST(tool_output_byte_budgets) {
     /* GUARD: absolute byte ceilings on default tool outputs. Re-bloat (e.g.
      * a property blob sneaking back into row emission — the fp field alone
@@ -2109,11 +3016,18 @@ TEST(tool_lean_defaults_schema_and_status) {
     n.end_line = 2;
     n.properties_json = "{\"fp\":\"x\",\"sp\":\"y\",\"bt\":\"z\",\"complexity\":3}";
     ASSERT_GT(cbm_store_upsert_node(st, &n), 0);
+    ASSERT_EQ(cbm_store_upsert_file_hash(st, "test-project", "src/lean-default-partial.c",
+                                         "fixture", 1, 1),
+              CBM_STORE_OK);
+    cbm_coverage_row_t coverage = {
+        .rel_path = "src/lean-default-partial.c", .kind = "parse_partial", .detail = "7-9"};
+    ASSERT_EQ(cbm_store_coverage_replace(st, "test-project", &coverage, 1), CBM_STORE_OK);
 
     char *resp =
         cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":48,\"method\":\"tools/call\","
                                    "\"params\":{\"name\":\"get_graph_schema\","
-                                   "\"arguments\":{\"project\":\"test-project\"}}}");
+                                   "\"arguments\":{\"project\":\"test-project\","
+                                   "\"diagnostics\":\"full\",\"format\":\"json\"}}}");
     ASSERT_NOT_NULL(resp);
     char *inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
@@ -2128,20 +3042,41 @@ TEST(tool_lean_defaults_schema_and_status) {
     /* index_status: no git block by default... */
     resp = cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":49,\"method\":\"tools/call\","
                                       "\"params\":{\"name\":\"index_status\","
-                                      "\"arguments\":{\"project\":\"test-project\"}}}");
+                                      "\"arguments\":{\"project\":\"test-project\","
+                                      "\"format\":\"json\"}}}");
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"status\":"));
+    ASSERT_NOT_NULL(strstr(inner, "\"indexed_at\":"));
+    ASSERT_NULL(strstr(inner, "\"git\":"));
+    ASSERT_NOT_NULL(strstr(inner, "\"parse_partial\":"));
+    ASSERT_NOT_NULL(strstr(inner, "\"count\":1"));
+    ASSERT_NOT_NULL(strstr(inner, "\"truncated\":true"));
+    ASSERT_NULL(strstr(inner, "src/lean-default-partial.c"));
+    free(inner);
+    free(resp);
+
+    /* Coverage identities are diagnostic detail: full restores the exact
+     * persisted path without changing the counts-only default. */
+    resp = cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":501,\"method\":\"tools/call\","
+                                      "\"params\":{\"name\":\"index_status\","
+                                      "\"arguments\":{\"project\":\"test-project\","
+                                      "\"diagnostics\":\"full\",\"format\":\"json\"}}}");
     ASSERT_NOT_NULL(resp);
     inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "\"status\""));
-    ASSERT_NULL(strstr(inner, "\"git\""));
+    ASSERT_NOT_NULL(strstr(inner, "src/lean-default-partial.c"));
+    ASSERT_NOT_NULL(strstr(inner, "\"count\":1"));
     free(inner);
     free(resp);
 
     /* ...and present with verbose:true. */
-    resp = cbm_mcp_server_handle(srv,
-                                 "{\"jsonrpc\":\"2.0\",\"id\":50,\"method\":\"tools/call\","
-                                 "\"params\":{\"name\":\"index_status\","
-                                 "\"arguments\":{\"project\":\"test-project\",\"verbose\":true}}}");
+    resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":50,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"index_status\","
+                                   "\"arguments\":{\"project\":\"test-project\",\"verbose\":true,"
+                                   "\"format\":\"json\"}}}");
     ASSERT_NOT_NULL(resp);
     inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
@@ -2246,7 +3181,7 @@ TEST(tool_output_regression_gate) {
          6000, "node_labels"},
         {"{\"jsonrpc\":\"2.0\",\"id\":72,\"method\":\"tools/call\",\"params\":{"
          "\"name\":\"index_status\",\"arguments\":{\"project\":\"test-project\"}}}",
-         7000, "\"status\""},
+         2500, "status:"},
         {"{\"jsonrpc\":\"2.0\",\"id\":73,\"method\":\"tools/call\",\"params\":{"
          "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"test-project\","
          "\"function_name\":\"HandleRequest\",\"direction\":\"both\"}}}",
@@ -2322,435 +3257,2009 @@ TEST(tool_search_graph_query_honors_file_pattern_issue552) {
     PASS();
 }
 
-/* Resource discovery methods this server doesn't populate must return EMPTY
- * lists, not -32601 Method-not-found: clients like Cline probe them on connect
- * and surface the errors as a failed connection (#958). */
-TEST(mcp_resource_discovery_methods_return_empty_lists) {
+TEST(tool_search_graph_bm25_reports_candidate_saturation) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "bm25-saturation";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/bm25-saturation"), CBM_STORE_OK);
+
+    for (int i = 0; i < 2001; i++) {
+        char qn[64];
+        snprintf(qn, sizeof(qn), "bm25-saturation.fn_%04d", i);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = "saturationneedle",
+                           .qualified_name = qn,
+                           .file_path = "many.c",
+                           .start_line = i + 1,
+                           .end_line = i + 1};
+        ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    }
+    ASSERT_EQ(cbm_store_exec(store, "INSERT INTO nodes_fts(nodes_fts) VALUES('delete-all');"),
+              CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_exec(store, "INSERT INTO nodes_fts(rowid, name, qualified_name, label, "
+                                    "file_path) SELECT id, cbm_camel_split(name), qualified_name, "
+                                    "label, file_path FROM nodes;"),
+              CBM_STORE_OK);
 
-    struct {
-        const char *method;
-        const char *want;
-    } cases[] = {
-        {"resources/list", "\"resources\":[]"},
-        {"resources/templates/list", "\"resourceTemplates\":[]"},
-    };
-    for (int i = 0; i < 2; i++) {
-        char reqbuf[256];
-        snprintf(reqbuf, sizeof(reqbuf), "{\"jsonrpc\":\"2.0\",\"id\":%d,\"method\":\"%s\"}",
-                 100 + i, cases[i].method);
-        char *resp = cbm_mcp_server_handle(srv, reqbuf);
-        ASSERT_NOT_NULL(resp);
-        ASSERT_NULL(strstr(resp, "Method not found"));
-        ASSERT_NOT_NULL(strstr(resp, cases[i].want));
-        free(resp);
-    }
-
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":553,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"search_graph\",\"arguments\":{"
+                                   "\"project\":\"bm25-saturation\",\"query\":\"saturationneedle\","
+                                   "\"limit\":10,\"format\":\"json\"}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"total\":2000"));
+    ASSERT_NOT_NULL(strstr(inner, "\"total_relation\":\"gte\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"candidate_window_saturated\":true"));
+    ASSERT_NOT_NULL(strstr(inner, "\"truncated\":true"));
+    free(inner);
+    free(resp);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-TEST(tool_query_graph_basic) {
-    cbm_mcp_server_t *srv = setup_mcp_with_data();
+/* `query` selects the BM25 fast path, which returns before semantic_query is
+ * evaluated. Accepting both therefore used to report success while silently
+ * discarding one of the caller's two requested result sets. The contract is
+ * deliberately fail-closed: callers choose one ranking model per request. */
+TEST(tool_search_graph_rejects_bm25_and_semantic_query_together) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "mixed-search-modes";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/mixed-search-modes"), CBM_STORE_OK);
 
-    char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":14,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"query_graph\","
-             "\"arguments\":{\"query\":\"MATCH (f:Function) RETURN f.name\"}}}");
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "\"result\""));
-    free(resp);
+    cbm_node_t node = {.project = project,
+                       .label = "Function",
+                       .name = "mixedneedle",
+                       .qualified_name = "mixed-search-modes.mixedneedle",
+                       .file_path = "mixed.c",
+                       .start_line = 1,
+                       .end_line = 1};
+    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    ASSERT_EQ(cbm_store_exec(store, "INSERT INTO nodes_fts(nodes_fts) VALUES('delete-all');"),
+              CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_exec(store, "INSERT INTO nodes_fts(rowid, name, qualified_name, label, "
+                                    "file_path) SELECT id, cbm_camel_split(name), qualified_name, "
+                                    "label, file_path FROM nodes;"),
+              CBM_STORE_OK);
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "search_graph",
+                            "{\"project\":\"mixed-search-modes\",\"query\":\"mixedneedle\","
+                            "\"semantic_query\":[\"meaning\"],\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    ASSERT_NOT_NULL(strstr(response, "\"isError\":true"));
+    ASSERT_NOT_NULL(strstr(response, "query and semantic_query are mutually exclusive"));
+    ASSERT_NULL(strstr(response, "\"search_mode\":\"bm25\""));
+    free(response);
+
+    char *tools = cbm_mcp_tools_list();
+    ASSERT_NOT_NULL(tools);
+    ASSERT_NOT_NULL(strstr(tools, "Not with query"));
+    free(tools);
 
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-TEST(tool_index_status_no_project) {
-    cbm_mcp_server_t *srv = setup_mcp_with_data();
+/* The public schema accepts semantic_offset only through 99,998. A page at
+ * that boundary used to emit semantic_next_offset:99,999; the handler then
+ * clamped replay back to 99,998, repeating the same row forever. At the engine
+ * boundary we must report an explicit lower-bound saturation and no cursor. */
+TEST(tool_search_graph_semantic_ceiling_never_emits_unusable_continuation) {
+    char *json = cbm_mcp_render_semantic_paging_for_testing(100000, 99998, 1, 1, false, true);
+    ASSERT_NOT_NULL(json);
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "semantic_total_relation")), "gte");
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "semantic_has_more")));
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "semantic_engine_saturated")));
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "semantic_continuation_unavailable")));
+    ASSERT_NULL(yyjson_obj_get(root, "semantic_next_offset"));
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    ASSERT_NULL(yyjson_obj_get(root, "next_offset"));
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "truncated")));
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "truncation_reason")), "engine_limit");
+    yyjson_doc_free(doc);
+    free(json);
 
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":15,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"index_status\",\"arguments\":{}}}");
-    ASSERT_NOT_NULL(resp);
-    /* Should return error or empty status */
-    ASSERT_NOT_NULL(strstr(resp, "\"result\""));
-    free(resp);
+    /* Even a fully materialized total becomes a lower-bound report when the
+     * byte budget returns too few rows to reach it with a legal next offset. */
+    json = cbm_mcp_render_semantic_paging_for_testing(100000, 99998, 1, 2, true, true);
+    ASSERT_NOT_NULL(json);
+    doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "semantic_total_relation")), "gte");
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "semantic_engine_saturated")));
+    ASSERT_NULL(yyjson_obj_get(root, "semantic_next_offset"));
+    ASSERT_NULL(yyjson_obj_get(root, "next_offset"));
+    yyjson_doc_free(doc);
+    free(json);
+
+    char *tree = cbm_mcp_render_semantic_paging_for_testing(100000, 99998, 1, 1, false, false);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NOT_NULL(strstr(tree, "semantic_total_relation: gte"));
+    ASSERT_NOT_NULL(strstr(tree, "semantic_has_more: false"));
+    ASSERT_NOT_NULL(strstr(tree, "semantic_engine_saturated: true"));
+    ASSERT_NOT_NULL(strstr(tree, "semantic_continuation_unavailable: true"));
+    ASSERT_NULL(strstr(tree, "semantic_next_offset:"));
+    ASSERT_NOT_NULL(strstr(tree, "has_more: false"));
+    ASSERT_NULL(strstr(tree, "next_offset:"));
+    ASSERT_NOT_NULL(strstr(tree, "truncated: true"));
+    ASSERT_NOT_NULL(strstr(tree, "truncation_reason: engine_limit"));
+    free(tree);
+
+    /* One row earlier, next=99,998 is still valid and must remain available. */
+    json = cbm_mcp_render_semantic_paging_for_testing(100000, 99997, 1, 1, false, true);
+    ASSERT_NOT_NULL(json);
+    doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "semantic_has_more")));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "semantic_next_offset")), 99998);
+    ASSERT_NULL(yyjson_obj_get(root, "semantic_engine_saturated"));
+    ASSERT_NULL(yyjson_obj_get(root, "semantic_continuation_unavailable"));
+    yyjson_doc_free(doc);
+    free(json);
 
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    cbm_mcp_server_set_project(srv, "semantic-ceiling");
+    ASSERT_EQ(cbm_store_upsert_project(store, "semantic-ceiling", "/tmp/semantic-ceiling"),
+              CBM_STORE_OK);
+    char *response =
+        cbm_mcp_handle_tool(srv, "search_graph",
+                            "{\"project\":\"semantic-ceiling\",\"semantic_query\":[\"x\"],"
+                            "\"semantic_offset\":99999,\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    ASSERT_NOT_NULL(strstr(response, "\"isError\":true"));
+    ASSERT_NOT_NULL(strstr(response, "semantic_offset maximum is 99998"));
+    free(response);
     cbm_mcp_server_free(srv);
+
+    char *tools = cbm_mcp_tools_list();
+    ASSERT_NOT_NULL(tools);
+    ASSERT_NOT_NULL(strstr(tools, "\"semantic_offset\":{\"type\":\"integer\",\"default\":0,"
+                                  "\"minimum\":0,\"maximum\":99998}"));
+    free(tools);
     PASS();
 }
 
-/* Reproduce the exact-file false negative in the current Read hook: index_status
- * intentionally caps each coverage category at 500 entries, so a later path is
- * absent even though the authoritative index_coverage table contains it.  The
- * targeted coverage tool must query that table rather than scan the capped
- * presentation response. */
-TEST(tool_check_index_coverage_finds_path_beyond_status_cap) {
-    enum { ROW_COUNT = 502 };
+enum { MCP_TEST_SEMANTIC_VECTOR_DIM = 768 };
+
+static int mcp_test_insert_semantic_vector(cbm_store_t *store, const char *table,
+                                           const char *project, int64_t node_id, const char *token,
+                                           unsigned char primary, unsigned char secondary) {
+    unsigned char vector[MCP_TEST_SEMANTIC_VECTOR_DIM] = {0};
+    char hex[MCP_TEST_SEMANTIC_VECTOR_DIM * 2 + 1];
+    static const char digits[] = "0123456789abcdef";
+    vector[0] = primary;
+    vector[1] = secondary;
+    for (int i = 0; i < MCP_TEST_SEMANTIC_VECTOR_DIM; i++) {
+        hex[i * 2] = digits[vector[i] >> 4];
+        hex[i * 2 + 1] = digits[vector[i] & 0x0f];
+    }
+    hex[sizeof(hex) - 1] = '\0';
+
+    char sql[CBM_SZ_4K];
+    if (strcmp(table, "token_vectors") == 0) {
+        snprintf(sql, sizeof(sql),
+                 "INSERT INTO token_vectors(project,token,vector,idf) "
+                 "VALUES('%s','%s',X'%s',1);",
+                 project, token, hex);
+    } else {
+        snprintf(sql, sizeof(sql),
+                 "INSERT INTO node_vectors(node_id,project,vector) VALUES(%lld,'%s',X'%s');",
+                 (long long)node_id, project, hex);
+    }
+    return cbm_store_exec(store, sql);
+}
+
+static yyjson_doc *mcp_test_semantic_page(cbm_mcp_server_t *srv, const char *args,
+                                          char **out_response, char **out_inner) {
+    *out_response = cbm_mcp_handle_tool(srv, "search_graph", args);
+    *out_inner = extract_text_content(*out_response);
+    return *out_inner ? yyjson_read(*out_inner, strlen(*out_inner), 0) : NULL;
+}
+
+/* Semantic rows are their own ranked result set. Structural limit/offset must
+ * neither choose their page nor make a budget-trimmed tail unrecoverable. */
+TEST(tool_search_graph_semantic_pagination_is_lossless_and_independent) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(st);
-
-    const char *project = "coverage-cap-regression";
-    ASSERT_EQ(cbm_store_upsert_project(st, project, "/tmp/coverage-cap-regression"), CBM_STORE_OK);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "semantic-pagination";
+    const char *token = "semantic-page-token";
     cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/semantic-pagination"), CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_exec(store,
+                             "CREATE TABLE node_vectors(node_id INTEGER PRIMARY KEY,"
+                             "project TEXT NOT NULL,vector BLOB NOT NULL);"
+                             "CREATE TABLE token_vectors(id INTEGER PRIMARY KEY,"
+                             "project TEXT NOT NULL,token TEXT NOT NULL,vector BLOB NOT NULL,"
+                             "idf INTEGER NOT NULL);"),
+              CBM_STORE_OK);
+    ASSERT_EQ(mcp_test_insert_semantic_vector(store, "token_vectors", project, 0, token, 127, 0),
+              CBM_STORE_OK);
 
-    char (*paths)[64] = calloc(ROW_COUNT, sizeof(*paths));
-    cbm_coverage_row_t *rows = calloc(ROW_COUNT, sizeof(*rows));
-    ASSERT_NOT_NULL(paths);
-    ASSERT_NOT_NULL(rows);
-    for (int i = 0; i < ROW_COUNT; i++) {
-        snprintf(paths[i], sizeof(paths[i]), "src/partial-%04d.c", i);
-        rows[i].rel_path = paths[i];
-        rows[i].kind = "parse_partial";
-        rows[i].detail = i == ROW_COUNT - 1 ? "777-790" : "1-2";
-        ASSERT_EQ(cbm_store_upsert_file_hash(st, project, paths[i], "fixture", i + 1, 10),
+    char long_qn[900];
+    memset(long_qn, 'q', sizeof(long_qn) - 1);
+    long_qn[sizeof(long_qn) - 1] = '\0';
+    const char *expected[] = {long_qn,           "semantic.rank.2", "semantic.rank.3",
+                              "semantic.rank.4", "semantic.rank.5", "semantic.rank.6"};
+    for (int i = 0; i < 6; i++) {
+        char name[32];
+        char path[64];
+        snprintf(name, sizeof(name), "semantic_rank_%d", i + 1);
+        snprintf(path, sizeof(path), "src/semantic_rank_%d.c", i + 1);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = name,
+                           .qualified_name = expected[i],
+                           .file_path = path,
+                           .start_line = i + 1,
+                           .end_line = i + 1};
+        int64_t id = cbm_store_upsert_node(store, &node);
+        ASSERT_GT(id, 0);
+        ASSERT_EQ(mcp_test_insert_semantic_vector(store, "node_vectors", project, id, NULL, 127,
+                                                  (unsigned char)(i * 20)),
                   CBM_STORE_OK);
     }
-    ASSERT_EQ(cbm_store_coverage_replace(st, project, rows, ROW_COUNT), CBM_STORE_OK);
-
-    char *status =
-        cbm_mcp_handle_tool(srv, "index_status", "{\"project\":\"coverage-cap-regression\"}");
-    ASSERT_NOT_NULL(status);
-    char *status_inner = extract_text_content(status);
-    ASSERT_NOT_NULL(status_inner);
-    ASSERT_NOT_NULL(strstr(status_inner, "\"truncated\":true"));
-    ASSERT_NULL(strstr(status_inner, "src/partial-0501.c"));
-    free(status_inner);
-    free(status);
 
-    char *coverage = cbm_mcp_handle_tool(
-        srv, "check_index_coverage",
-        "{\"project\":\"coverage-cap-regression\",\"paths\":[\"src/partial-0501.c\"]}");
-    ASSERT_NOT_NULL(coverage);
-    char *coverage_inner = extract_text_content(coverage);
-    ASSERT_NOT_NULL(coverage_inner);
-    ASSERT_NOT_NULL(strstr(coverage_inner, "src/partial-0501.c"));
-    ASSERT_NOT_NULL(strstr(coverage_inner, "\"status\":\"partial\""));
-    ASSERT_NOT_NULL(strstr(coverage_inner, "777-790"));
+    char args[512];
+    char *response = NULL;
+    char *inner = NULL;
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"semantic_query\":[\"%s\"],"
+             "\"semantic_limit\":6,\"limit\":1,\"offset\":99,\"format\":\"json\"}",
+             project, token);
+    yyjson_doc *full_doc = mcp_test_semantic_page(srv, args, &response, &inner);
+    ASSERT_NOT_NULL(full_doc);
+    yyjson_val *full_root = yyjson_doc_get_root(full_doc);
+    yyjson_val *full_semantic = yyjson_obj_get(full_root, "semantic");
+    yyjson_val *full_rows = full_semantic ? yyjson_obj_get(full_semantic, "rows") : NULL;
+    ASSERT_EQ(yyjson_arr_size(full_rows), 6);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(full_root, "semantic_total")), 6);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(full_root, "semantic_total_relation")), "eq");
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(full_root, "semantic_has_more")));
+
+    for (int page = 0; page < 3; page++) {
+        int semantic_offset = page * 2;
+        snprintf(args, sizeof(args),
+                 "{\"project\":\"%s\",\"semantic_query\":[\"%s\"],"
+                 "\"semantic_offset\":%d,\"semantic_limit\":2,"
+                 "\"limit\":1,\"offset\":99,\"format\":\"json\"}",
+                 project, token, semantic_offset);
+        char *page_response = NULL;
+        char *page_inner = NULL;
+        yyjson_doc *page_doc = mcp_test_semantic_page(srv, args, &page_response, &page_inner);
+        ASSERT_NOT_NULL(page_doc);
+        yyjson_val *page_root = yyjson_doc_get_root(page_doc);
+        yyjson_val *page_semantic = yyjson_obj_get(page_root, "semantic");
+        yyjson_val *page_rows = page_semantic ? yyjson_obj_get(page_semantic, "rows") : NULL;
+        ASSERT_EQ(yyjson_arr_size(page_rows), 2);
+        ASSERT_EQ(yyjson_get_int(yyjson_obj_get(page_root, "semantic_returned")), 2);
+        for (int row = 0; row < 2; row++) {
+            const char *actual = yyjson_get_str(yyjson_arr_get(yyjson_arr_get(page_rows, row), 0));
+            const char *from_full =
+                yyjson_get_str(yyjson_arr_get(yyjson_arr_get(full_rows, semantic_offset + row), 0));
+            ASSERT_STR_EQ(actual, from_full);
+        }
+        bool want_more = page < 2;
+        ASSERT_EQ(yyjson_get_bool(yyjson_obj_get(page_root, "semantic_has_more")), want_more);
+        if (want_more) {
+            ASSERT_EQ(yyjson_get_int(yyjson_obj_get(page_root, "semantic_next_offset")),
+                      semantic_offset + 2);
+            ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(page_root, "semantic_total_relation")),
+                          "gte");
+        } else {
+            ASSERT_NULL(yyjson_obj_get(page_root, "semantic_next_offset"));
+            ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(page_root, "semantic_total_relation")),
+                          "eq");
+        }
+        yyjson_doc_free(page_doc);
+        free(page_inner);
+        free(page_response);
+    }
 
-    free(coverage_inner);
-    free(coverage);
-    free(rows);
-    free(paths);
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"name_pattern\":\".*\","
+             "\"semantic_query\":[\"%s\"],\"semantic_offset\":1,"
+             "\"semantic_limit\":2,\"limit\":1,\"offset\":4,\"format\":\"json\"}",
+             project, token);
+    char *combined_response = NULL;
+    char *combined_inner = NULL;
+    yyjson_doc *combined_doc =
+        mcp_test_semantic_page(srv, args, &combined_response, &combined_inner);
+    ASSERT_NOT_NULL(combined_doc);
+    yyjson_val *combined_root = yyjson_doc_get_root(combined_doc);
+    yyjson_val *combined_semantic = yyjson_obj_get(combined_root, "semantic");
+    yyjson_val *combined_rows =
+        combined_semantic ? yyjson_obj_get(combined_semantic, "rows") : NULL;
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(combined_root, "returned")), 1);
+    ASSERT_EQ(yyjson_arr_size(combined_rows), 2);
+    for (int row = 0; row < 2; row++) {
+        ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(yyjson_arr_get(combined_rows, row), 0)),
+                      yyjson_get_str(yyjson_arr_get(yyjson_arr_get(full_rows, row + 1), 0)));
+    }
+    yyjson_doc_free(combined_doc);
+    free(combined_inner);
+    free(combined_response);
+
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"semantic_query\":[\"%s\"],"
+             "\"semantic_offset\":2,\"semantic_limit\":2,\"limit\":1,\"offset\":99}",
+             project, token);
+    char *tree_response = cbm_mcp_handle_tool(srv, "search_graph", args);
+    char *tree = extract_text_content(tree_response);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NOT_NULL(strstr(tree, "semantic_total: 5"));
+    ASSERT_NOT_NULL(strstr(tree, "semantic_total_relation: gte"));
+    ASSERT_NOT_NULL(strstr(tree, "semantic_returned: 2"));
+    ASSERT_NOT_NULL(strstr(tree, "semantic_has_more: true"));
+    ASSERT_NOT_NULL(strstr(tree, "semantic_next_offset: 4"));
+    ASSERT_NOT_NULL(strstr(tree, "semantic.rank.3"));
+    ASSERT_NULL(strstr(tree, "semantic.rank.2"));
+    free(tree);
+    free(tree_response);
+
+    /* A byte budget may shorten this page, but continuation advances only by
+     * identities actually emitted. The first roomy retry row must therefore
+     * be the next row from the stable full ranking, with no gap. */
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"semantic_query\":[\"%s\"],"
+             "\"semantic_offset\":1,\"semantic_limit\":5,"
+             "\"max_output_tokens\":128,\"format\":\"json\"}",
+             project, token);
+    char *budget_response = NULL;
+    char *budget_inner = NULL;
+    yyjson_doc *budget_doc = mcp_test_semantic_page(srv, args, &budget_response, &budget_inner);
+    ASSERT_NOT_NULL(budget_doc);
+    yyjson_val *budget_root = yyjson_doc_get_root(budget_doc);
+    int budget_returned = (int)yyjson_get_int(yyjson_obj_get(budget_root, "semantic_returned"));
+    ASSERT_GT(budget_returned, 0);
+    ASSERT_LT(budget_returned, 5);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(budget_root, "semantic_has_more")));
+    int budget_next = (int)yyjson_get_int(yyjson_obj_get(budget_root, "semantic_next_offset"));
+    ASSERT_EQ(budget_next, 1 + budget_returned);
+    yyjson_doc_free(budget_doc);
+    free(budget_inner);
+    free(budget_response);
+
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"semantic_query\":[\"%s\"],"
+             "\"semantic_offset\":%d,\"semantic_limit\":1,\"format\":\"json\"}",
+             project, token, budget_next);
+    char *resume_response = NULL;
+    char *resume_inner = NULL;
+    yyjson_doc *resume_doc = mcp_test_semantic_page(srv, args, &resume_response, &resume_inner);
+    ASSERT_NOT_NULL(resume_doc);
+    yyjson_val *resume_semantic = yyjson_obj_get(yyjson_doc_get_root(resume_doc), "semantic");
+    yyjson_val *resume_rows = resume_semantic ? yyjson_obj_get(resume_semantic, "rows") : NULL;
+    ASSERT_EQ(yyjson_arr_size(resume_rows), 1);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(yyjson_arr_get(resume_rows, 0), 0)),
+                  yyjson_get_str(yyjson_arr_get(yyjson_arr_get(full_rows, budget_next), 0)));
+    yyjson_doc_free(resume_doc);
+    free(resume_inner);
+    free(resume_response);
+
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"semantic_query\":[\"%s\"],"
+             "\"semantic_limit\":0,\"format\":\"json\"}",
+             project, token);
+    char *zero_response = NULL;
+    char *zero_inner = NULL;
+    yyjson_doc *zero_doc = mcp_test_semantic_page(srv, args, &zero_response, &zero_inner);
+    ASSERT_NOT_NULL(zero_doc);
+    yyjson_val *zero_root = yyjson_doc_get_root(zero_doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(zero_root, "semantic_returned")), 0);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(zero_root, "semantic_has_more")));
+    ASSERT_TRUE(yyjson_get_bool(
+        yyjson_obj_get(zero_root, "semantic_continuation_requires_positive_limit")));
+    ASSERT_NULL(yyjson_obj_get(zero_root, "semantic_next_offset"));
+    yyjson_doc_free(zero_doc);
+    free(zero_inner);
+    free(zero_response);
+
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"semantic_query\":[\"%s\"],"
+             "\"semantic_limit\":1,\"max_output_tokens\":128,\"format\":\"json\"}",
+             project, token);
+    char *floor_response = NULL;
+    char *floor_inner = NULL;
+    yyjson_doc *floor_doc = mcp_test_semantic_page(srv, args, &floor_response, &floor_inner);
+    ASSERT_NOT_NULL(floor_doc);
+    ASSERT_TRUE(strlen(floor_inner) <= 512U);
+    yyjson_val *floor_root = yyjson_doc_get_root(floor_doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(floor_root, "semantic_returned")), 0);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(floor_root, "semantic_has_more")));
+    ASSERT_TRUE(yyjson_get_bool(
+        yyjson_obj_get(floor_root, "semantic_continuation_requires_higher_budget")));
+    ASSERT_NULL(yyjson_obj_get(floor_root, "semantic_next_offset"));
+    yyjson_doc_free(floor_doc);
+    free(floor_inner);
+    free(floor_response);
+
+    /* Multi-keyword min-cosine ranking must not depend on how deep a page asks
+     * the first-keyword prefilter to materialize. Fifteen first-keyword-heavy
+     * decoys put the genuinely balanced result just beyond the initial 5x
+     * window; every small page must still equal the corresponding full ranks. */
+    const char *stable_project = "semantic-page-stability";
+    const char *first_token = "semantic-rank-first";
+    const char *second_token = "semantic-rank-second";
+    ASSERT_EQ(cbm_store_upsert_project(store, stable_project, "/tmp/semantic-page-stability"),
+              CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, stable_project);
+    ASSERT_EQ(mcp_test_insert_semantic_vector(store, "token_vectors", stable_project, 0,
+                                              first_token, 127, 0),
+              CBM_STORE_OK);
+    ASSERT_EQ(mcp_test_insert_semantic_vector(store, "token_vectors", stable_project, 0,
+                                              second_token, 0, 127),
+              CBM_STORE_OK);
+    for (int i = 0; i < 16; i++) {
+        char name[40];
+        char qn[64];
+        snprintf(name, sizeof(name), "stable_rank_%02d", i + 1);
+        snprintf(qn, sizeof(qn), "semantic.stable.%02d", i + 1);
+        cbm_node_t node = {.project = stable_project,
+                           .label = "Function",
+                           .name = name,
+                           .qualified_name = qn,
+                           .file_path = "src/semantic_stable.c",
+                           .start_line = i + 1,
+                           .end_line = i + 1};
+        int64_t id = cbm_store_upsert_node(store, &node);
+        ASSERT_GT(id, 0);
+        unsigned char primary = i == 15 ? 90 : 127;
+        unsigned char secondary = i == 15 ? 90 : (unsigned char)(i + 1);
+        ASSERT_EQ(mcp_test_insert_semantic_vector(store, "node_vectors", stable_project, id, NULL,
+                                                  primary, secondary),
+                  CBM_STORE_OK);
+    }
+
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"semantic_query\":[\"%s\",\"%s\"],"
+             "\"semantic_limit\":16,\"format\":\"json\"}",
+             stable_project, first_token, second_token);
+    char *stable_full_response = NULL;
+    char *stable_full_inner = NULL;
+    yyjson_doc *stable_full_doc =
+        mcp_test_semantic_page(srv, args, &stable_full_response, &stable_full_inner);
+    ASSERT_NOT_NULL(stable_full_doc);
+    yyjson_val *stable_full_semantic =
+        yyjson_obj_get(yyjson_doc_get_root(stable_full_doc), "semantic");
+    yyjson_val *stable_full_rows =
+        stable_full_semantic ? yyjson_obj_get(stable_full_semantic, "rows") : NULL;
+    ASSERT_EQ(yyjson_arr_size(stable_full_rows), 16);
+    for (int page = 0; page < 2; page++) {
+        int stable_offset = page * 2;
+        snprintf(args, sizeof(args),
+                 "{\"project\":\"%s\",\"semantic_query\":[\"%s\",\"%s\"],"
+                 "\"semantic_offset\":%d,\"semantic_limit\":2,\"format\":\"json\"}",
+                 stable_project, first_token, second_token, stable_offset);
+        char *stable_page_response = NULL;
+        char *stable_page_inner = NULL;
+        yyjson_doc *stable_page_doc =
+            mcp_test_semantic_page(srv, args, &stable_page_response, &stable_page_inner);
+        ASSERT_NOT_NULL(stable_page_doc);
+        yyjson_val *stable_page_semantic =
+            yyjson_obj_get(yyjson_doc_get_root(stable_page_doc), "semantic");
+        yyjson_val *stable_page_rows =
+            stable_page_semantic ? yyjson_obj_get(stable_page_semantic, "rows") : NULL;
+        ASSERT_EQ(yyjson_arr_size(stable_page_rows), 2);
+        for (int row = 0; row < 2; row++) {
+            ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(yyjson_arr_get(stable_page_rows, row), 0)),
+                          yyjson_get_str(yyjson_arr_get(
+                              yyjson_arr_get(stable_full_rows, stable_offset + row), 0)));
+        }
+        yyjson_doc_free(stable_page_doc);
+        free(stable_page_inner);
+        free(stable_page_response);
+    }
+    yyjson_doc_free(stable_full_doc);
+    free(stable_full_inner);
+    free(stable_full_response);
+
+    char *tools = cbm_mcp_tools_list();
+    ASSERT_NOT_NULL(tools);
+    ASSERT_NOT_NULL(strstr(tools, "semantic_offset"));
+    ASSERT_NOT_NULL(strstr(tools, "semantic_limit"));
+    free(tools);
+
+    yyjson_doc_free(full_doc);
+    free(inner);
+    free(response);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-TEST(tool_check_index_coverage_reports_paths_scopes_and_ranges) {
-    char tmp[256];
-    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+TEST(tool_search_graph_budget_preserves_long_values_and_continuation) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(st);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-byte-budget";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/search-byte-budget"), CBM_STORE_OK);
+
+    enum { PREFIX_LEN = 3900, PATH_LEN = 3900, DOC_LEN = 5000 };
+    char *prefix = malloc(PREFIX_LEN + 1U);
+    char *path_a = malloc(PATH_LEN + 1U);
+    char *path_b = malloc(PATH_LEN + 1U);
+    char *doc_value = malloc(DOC_LEN + 1U);
+    char *qn_a = malloc(PREFIX_LEN + sizeof(".a_budget"));
+    char *qn_b = malloc(PREFIX_LEN + sizeof(".b_budget"));
+    char *properties = malloc(DOC_LEN + sizeof("{\"doc\":\"\"}"));
+    ASSERT_NOT_NULL(prefix);
+    ASSERT_NOT_NULL(path_a);
+    ASSERT_NOT_NULL(path_b);
+    ASSERT_NOT_NULL(doc_value);
+    ASSERT_NOT_NULL(qn_a);
+    ASSERT_NOT_NULL(qn_b);
+    ASSERT_NOT_NULL(properties);
+    memset(prefix, 'q', PREFIX_LEN);
+    prefix[PREFIX_LEN] = '\0';
+    memset(path_a, 'a', PATH_LEN);
+    memset(path_b, 'b', PATH_LEN);
+    path_a[PATH_LEN] = '\0';
+    path_b[PATH_LEN] = '\0';
+    memset(doc_value, 'v', DOC_LEN);
+    doc_value[DOC_LEN] = '\0';
+    snprintf(qn_a, PREFIX_LEN + sizeof(".a_budget"), "%s.a_budget", prefix);
+    snprintf(qn_b, PREFIX_LEN + sizeof(".b_budget"), "%s.b_budget", prefix);
+    snprintf(properties, DOC_LEN + sizeof("{\"doc\":\"\"}"), "{\"doc\":\"%s\"}", doc_value);
+
+    cbm_node_t first = {.project = project,
+                        .label = "Function",
+                        .name = "a_budget",
+                        .qualified_name = qn_a,
+                        .file_path = path_a,
+                        .start_line = 1,
+                        .end_line = 2,
+                        .properties_json = properties};
+    cbm_node_t second = {.project = project,
+                         .label = "Function",
+                         .name = "b_budget",
+                         .qualified_name = qn_b,
+                         .file_path = path_b,
+                         .start_line = 3,
+                         .end_line = 4,
+                         .properties_json = properties};
+    ASSERT_GT(cbm_store_upsert_node(store, &first), 0);
+    ASSERT_GT(cbm_store_upsert_node(store, &second), 0);
+    ASSERT_EQ(cbm_store_exec(store, "INSERT INTO nodes_fts(nodes_fts) VALUES('delete-all');"),
+              CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_exec(store, "INSERT INTO nodes_fts(rowid, name, qualified_name, label, "
+                                    "file_path) SELECT id, cbm_camel_split(name), qualified_name, "
+                                    "label, file_path FROM nodes;"),
+              CBM_STORE_OK);
 
-    ASSERT_EQ(cbm_store_upsert_file_hash(st, "test-project", "main.go", "", 0, 0), CBM_STORE_OK);
-    ASSERT_EQ(cbm_store_upsert_file_hash(st, "test-project", "src/skip.c", "", 0, 0), CBM_STORE_OK);
-    cbm_coverage_row_t rows[] = {
-        {.rel_path = "main.go", .kind = "parse_partial", .detail = "3-4,9"},
-        {.rel_path = "generated", .kind = "not_indexed_dir", .detail = "excluded subtree"},
-        {.rel_path = "src/skip.c", .kind = "oversized", .detail = "file exceeds cap"},
-    };
-    ASSERT_EQ(cbm_store_coverage_replace(st, "test-project", rows, 3), CBM_STORE_OK);
+    /* Roomy tree and JSON carry the complete multi-KiB qn prefix, path, and
+     * requested property value. Grouping is a directory-like representation,
+     * never character truncation. */
+    const char *roomy_args = "{\"project\":\"search-byte-budget\",\"name_pattern\":\"._budget\","
+                             "\"fields\":[\"doc\"],\"limit\":2,\"max_output_tokens\":100000}";
+    char *response = cbm_mcp_handle_tool(srv, "search_graph", roomy_args);
+    char *tree = extract_text_content(response);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NOT_NULL(strstr(tree, prefix));
+    ASSERT_NOT_NULL(strstr(tree, path_a));
+    ASSERT_NOT_NULL(strstr(tree, path_b));
+    ASSERT_NOT_NULL(strstr(tree, doc_value));
+    ASSERT_NOT_NULL(strstr(tree, "a_budget"));
+    ASSERT_NOT_NULL(strstr(tree, "b_budget"));
+    free(response);
 
-    char *coverage =
-        cbm_mcp_handle_tool(srv, "check_index_coverage",
-                            "{\"project\":\"test-project\","
-                            "\"paths\":[\"main.go\",\"generated/pkg/a.c\",\"../escape.c\"],"
-                            "\"scopes\":[\".\"]}");
-    ASSERT_NOT_NULL(coverage);
-    char *inner = extract_text_content(coverage);
-    ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "\"path\":\"main.go\""));
-    ASSERT_NOT_NULL(strstr(inner, "\"status\":\"partial\""));
-    ASSERT_NOT_NULL(strstr(inner, "\"start\":3"));
-    ASSERT_NOT_NULL(strstr(inner, "\"end\":4"));
-    ASSERT_NOT_NULL(strstr(inner, "\"start\":9"));
-    ASSERT_NOT_NULL(strstr(inner, "generated/pkg/a.c"));
-    ASSERT_NOT_NULL(strstr(inner, "not_indexed_dir"));
-    ASSERT_NOT_NULL(strstr(inner, "outside_project"));
-    ASSERT_NOT_NULL(strstr(inner, "src/skip.c"));
-    ASSERT_NOT_NULL(strstr(inner, "file exceeds cap"));
-    ASSERT_NOT_NULL(strstr(inner, "best_effort"));
+    const char *roomy_json_args =
+        "{\"project\":\"search-byte-budget\",\"name_pattern\":\"._budget\","
+        "\"fields\":[\"doc\"],\"limit\":2,\"max_output_tokens\":100000,"
+        "\"format\":\"json\"}";
+    response = cbm_mcp_handle_tool(srv, "search_graph", roomy_json_args);
+    char *json = extract_text_content(response);
+    ASSERT_NOT_NULL(json);
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *groups = yyjson_obj_get(root, "groups");
+    ASSERT_EQ(yyjson_arr_size(groups), 2);
+    for (int i = 0; i < 2; i++) {
+        yyjson_val *group = yyjson_arr_get(groups, (size_t)i);
+        yyjson_val *rows = yyjson_obj_get(group, "rows");
+        yyjson_val *row = yyjson_arr_get(rows, 0);
+        ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(group, "qn_prefix")), prefix);
+        ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(group, "file")), i == 0 ? path_a : path_b);
+        ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(row, 0)), i == 0 ? "a_budget" : "b_budget");
+        ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(row, 5)), doc_value);
+    }
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 2);
+    yyjson_doc_free(doc);
 
-    free(inner);
-    free(coverage);
+    /* Default budget drops the optional 5 KiB field, then the lower-ranked
+     * complete row. The continuation returns that full row without overlap. */
+    const char *page_args = "{\"project\":\"search-byte-budget\",\"name_pattern\":\"._budget\","
+                            "\"fields\":[\"doc\"],\"limit\":2}";
+    char *page_response = cbm_mcp_handle_tool(srv, "search_graph", page_args);
+    char *page = extract_text_content(page_response);
+    ASSERT_NOT_NULL(page);
+    ASSERT_TRUE(strlen(page) <= 12800U);
+    ASSERT_NOT_NULL(strstr(page, prefix));
+    ASSERT_NOT_NULL(strstr(page, path_a));
+    ASSERT_NOT_NULL(strstr(page, "a_budget"));
+    ASSERT_NULL(strstr(page, path_b));
+    ASSERT_NULL(strstr(page, doc_value));
+    ASSERT_NOT_NULL(strstr(page, "returned: 1"));
+    ASSERT_NOT_NULL(strstr(page, "next_offset: 1"));
+    ASSERT_NOT_NULL(strstr(page, "fields_omitted: 1"));
+    ASSERT_NOT_NULL(strstr(page, "truncation_reason: output_budget"));
+
+    const char *next_args = "{\"project\":\"search-byte-budget\",\"name_pattern\":\"._budget\","
+                            "\"limit\":2,\"offset\":1}";
+    char *next_response = cbm_mcp_handle_tool(srv, "search_graph", next_args);
+    char *next = extract_text_content(next_response);
+    ASSERT_NOT_NULL(next);
+    ASSERT_NOT_NULL(strstr(next, prefix));
+    ASSERT_NOT_NULL(strstr(next, path_b));
+    ASSERT_NOT_NULL(strstr(next, "b_budget"));
+    ASSERT_NULL(strstr(next, path_a));
+    ASSERT_NOT_NULL(strstr(next, "returned: 1"));
+    ASSERT_NOT_NULL(strstr(next, "has_more: false"));
+
+    /* If mandatory identity cannot fit, both encodings return bounded,
+     * machine-readable floor metadata and no partial identifier fragment. */
+    const char *formats[] = {"tree", "json"};
+    for (int i = 0; i < 2; i++) {
+        char args[256];
+        snprintf(args, sizeof(args),
+                 "{\"project\":\"search-byte-budget\",\"name_pattern\":\"a_budget\","
+                 "\"max_output_tokens\":128,\"format\":\"%s\"}",
+                 formats[i]);
+        char *floor_response = cbm_mcp_handle_tool(srv, "search_graph", args);
+        char *floor = extract_text_content(floor_response);
+        ASSERT_NOT_NULL(floor);
+        ASSERT_TRUE(strlen(floor) <= 512U);
+        ASSERT_NOT_NULL(strstr(floor, "output_budget_floor_exceeded"));
+        ASSERT_NOT_NULL(strstr(floor, "continuation_requires_higher_budget"));
+        ASSERT_NULL(strstr(floor, "next_offset"));
+        ASSERT_NULL(strstr(floor, prefix));
+        ASSERT_NULL(strstr(floor, path_a));
+        free(floor);
+        free(floor_response);
+    }
+
+    char *bm25_floor_response =
+        cbm_mcp_handle_tool(srv, "search_graph",
+                            "{\"project\":\"search-byte-budget\",\"query\":\"budget\","
+                            "\"max_output_tokens\":128,\"format\":\"json\"}");
+    char *bm25_floor = extract_text_content(bm25_floor_response);
+    ASSERT_NOT_NULL(bm25_floor);
+    ASSERT_NOT_NULL(strstr(bm25_floor, "continuation_requires_higher_budget"));
+    ASSERT_NULL(strstr(bm25_floor, "next_offset"));
+    ASSERT_NULL(strstr(bm25_floor, prefix));
+    free(bm25_floor);
+    free(bm25_floor_response);
+
+    free(next);
+    free(next_response);
+    free(page);
+    free(page_response);
+    free(json);
+    free(response);
+    free(tree);
+    free(prefix);
+    free(path_a);
+    free(path_b);
+    free(doc_value);
+    free(qn_a);
+    free(qn_b);
+    free(properties);
     cbm_mcp_server_free(srv);
-    cleanup_snippet_dir(tmp);
     PASS();
 }
 
-TEST(tool_check_index_coverage_preserves_multiple_scope_labels) {
-    char tmp[256];
-    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+/* Resource discovery methods this server doesn't populate must return EMPTY
+ * lists, not -32601 Method-not-found: clients like Cline probe them on connect
+ * and surface the errors as a failed connection (#958). */
+TEST(mcp_resource_discovery_methods_return_empty_lists) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
 
-    char *coverage = cbm_mcp_handle_tool(srv, "check_index_coverage",
-                                         "{\"project\":\"test-project\","
-                                         "\"scopes\":[\"alpha/one\",\"bravo/two\",\"charl/tri\"]}");
-    ASSERT_NOT_NULL(coverage);
-    char *inner = extract_text_content(coverage);
-    ASSERT_NOT_NULL(inner);
-    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
-    ASSERT_NOT_NULL(doc);
-    yyjson_val *scopes = yyjson_obj_get(yyjson_doc_get_root(doc), "scopes");
-    ASSERT_NOT_NULL(scopes);
-    ASSERT_TRUE(yyjson_is_arr(scopes));
-    ASSERT_EQ(yyjson_arr_size(scopes), 3);
-
-    const char *expected[] = {"alpha/one", "bravo/two", "charl/tri"};
-    for (size_t i = 0; i < 3; i++) {
-        yyjson_val *scope = yyjson_obj_get(yyjson_arr_get(scopes, i), "scope");
-        ASSERT_NOT_NULL(scope);
-        ASSERT_TRUE(yyjson_is_str(scope));
-        ASSERT_STR_EQ(yyjson_get_str(scope), expected[i]);
+    struct {
+        const char *method;
+        const char *want;
+    } cases[] = {
+        {"resources/list", "\"resources\":[]"},
+        {"resources/templates/list", "\"resourceTemplates\":[]"},
+    };
+    for (int i = 0; i < 2; i++) {
+        char reqbuf[256];
+        snprintf(reqbuf, sizeof(reqbuf), "{\"jsonrpc\":\"2.0\",\"id\":%d,\"method\":\"%s\"}",
+                 100 + i, cases[i].method);
+        char *resp = cbm_mcp_server_handle(srv, reqbuf);
+        ASSERT_NOT_NULL(resp);
+        ASSERT_NULL(strstr(resp, "Method not found"));
+        ASSERT_NOT_NULL(strstr(resp, cases[i].want));
+        free(resp);
     }
 
-    yyjson_doc_free(doc);
-    free(inner);
-    free(coverage);
     cbm_mcp_server_free(srv);
-    cleanup_snippet_dir(tmp);
     PASS();
 }
 
-static int write_coverage_meta(cbm_store_t *store, const char *generation,
-                               const char *recording_status) {
-    cbm_coverage_meta_t meta = {
-        .generation = generation,
-        .index_mode = "fast",
-        .recorded_at = "2026-07-12T00:00:00Z",
-        .recording_status = recording_status,
-        .ignored_files_stored = 0,
-        .ignored_files_total = 0,
-        .coverage_version = 1,
-        .hash_records_complete = true,
-    };
-    return cbm_store_coverage_replace_ex(store, "test-project", NULL, 0, &meta);
+TEST(tool_query_graph_basic) {
+    cbm_mcp_server_t *srv = setup_mcp_with_data();
+
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":14,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"query_graph\","
+             "\"arguments\":{\"query\":\"MATCH (f:Function) RETURN f.name\"}}}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "\"result\""));
+    free(resp);
+
+    cbm_mcp_server_free(srv);
+    PASS();
 }
 
-TEST(tool_check_index_coverage_rejects_stale_generation) {
-    char tmp[256];
-    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+TEST(tool_query_graph_default_budget_is_truthful_and_expandable) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
     cbm_store_t *store = cbm_mcp_server_store(srv);
     ASSERT_NOT_NULL(store);
-    ASSERT_EQ(write_coverage_meta(store, "stale-generation", "complete"), CBM_STORE_OK);
+    const char *project = "query-budget";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/query-budget"), CBM_STORE_OK);
+    for (int i = 0; i < 202; i++) {
+        char name[32];
+        char qualified_name[64];
+        snprintf(name, sizeof(name), "row_%03d", i);
+        snprintf(qualified_name, sizeof(qualified_name), "query-budget.rows.%s", name);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = name,
+                           .qualified_name = qualified_name,
+                           .file_path = "rows.c",
+                           .start_line = i + 1,
+                           .end_line = i + 1};
+        ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    }
 
-    char *response = cbm_mcp_handle_tool(srv, "check_index_coverage",
-                                         "{\"project\":\"test-project\",\"paths\":[\"main.go\"]}");
+    char *response = cbm_mcp_handle_tool(
+        srv, "query_graph",
+        "{\"project\":\"query-budget\",\"query\":\"MATCH (n) RETURN n.name ORDER BY n.name\","
+        "\"format\":\"json\",\"max_output_tokens\":20000}");
     ASSERT_NOT_NULL(response);
     char *inner = extract_text_content(response);
     ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "\"generation_matches\":false"));
-    ASSERT_NOT_NULL(strstr(inner, "\"status\":\"coverage_unavailable\""));
-    ASSERT_NOT_NULL(strstr(inner, "\"recommended_action\":\"read_source_and_reindex\""));
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *rows = yyjson_obj_get(root, "rows");
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 200);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "total")), 202);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "total_relation")), "eq");
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "truncation_reason")), "page_limit");
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "next_offset")), 200);
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "rows")), 200);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
 
+    /* Response paging keeps the same evaluated result set and row order. */
+    response = cbm_mcp_handle_tool(
+        srv, "query_graph",
+        "{\"project\":\"query-budget\",\"query\":\"MATCH (n) RETURN n.name ORDER BY n.name\","
+        "\"format\":\"json\",\"offset\":200,\"max_output_tokens\":20000}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 2);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "offset")), 200);
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    rows = yyjson_obj_get(root, "rows");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(yyjson_arr_get_first(rows), 0)), "row_200");
+    yyjson_doc_free(doc);
     free(inner);
     free(response);
-    cbm_mcp_server_free(srv);
-    cleanup_snippet_dir(tmp);
-    PASS();
-}
 
-TEST(tool_check_index_coverage_requires_source_when_file_metadata_changed) {
-    char tmp[256];
-    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
-    ASSERT_NOT_NULL(srv);
-    cbm_store_t *store = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(store);
-    cbm_project_t project = {0};
-    ASSERT_EQ(cbm_store_get_project(store, "test-project", &project), CBM_STORE_OK);
-    ASSERT_EQ(write_coverage_meta(store, project.indexed_at, "complete"), CBM_STORE_OK);
-    cbm_project_free_fields(&project);
-    ASSERT_EQ(cbm_store_upsert_file_hash(store, "test-project", "main.go", "fixture", 0, 0),
-              CBM_STORE_OK);
+    response = cbm_mcp_handle_tool(
+        srv, "query_graph",
+        "{\"project\":\"query-budget\",\"query\":\"MATCH (n) RETURN n.name ORDER BY n.name\","
+        "\"format\":\"json\",\"max_rows\":250,\"max_output_tokens\":20000}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 202);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "total")), 202);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "total_relation")), "eq");
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
 
-    char *response = cbm_mcp_handle_tool(srv, "check_index_coverage",
-                                         "{\"project\":\"test-project\",\"paths\":[\"main.go\"]}");
+    /* Legacy max_rows=0 remains the spelling for the maximum visible window. */
+    response = cbm_mcp_handle_tool(
+        srv, "query_graph",
+        "{\"project\":\"query-budget\",\"query\":\"MATCH (n) RETURN n.name ORDER BY n.name\","
+        "\"format\":\"json\",\"max_rows\":0,\"max_output_tokens\":20000}");
     ASSERT_NOT_NULL(response);
-    char *inner = extract_text_content(response);
+    inner = extract_text_content(response);
     ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "\"generation_matches\":true"));
-    ASSERT_NOT_NULL(strstr(inner, "\"freshness\":\"metadata_changed\""));
-    ASSERT_NOT_NULL(strstr(inner, "\"recommended_action\":\"read_source_and_reindex\""));
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 202);
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* The display limit must not become a pre-aggregation/pre-SKIP execution
+     * cap. Both answers need all 202 bindings even though max_rows defaults to
+     * 200. This is RED if handle_query_graph executes with limit+1. */
+    response = cbm_mcp_handle_tool(
+        srv, "query_graph",
+        "{\"project\":\"query-budget\",\"query\":\"MATCH (n) RETURN count(*) AS n\","
+        "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    rows = yyjson_obj_get(root, "rows");
+    ASSERT_EQ(yyjson_arr_size(rows), 1);
+    yyjson_val *first = yyjson_arr_get_first(rows);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(first, 0)), "202");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "total_relation")), "eq");
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
 
+    response = cbm_mcp_handle_tool(srv, "query_graph",
+                                   "{\"project\":\"query-budget\","
+                                   "\"query\":\"MATCH (n) RETURN n.name ORDER BY n.name SKIP 200\","
+                                   "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 2);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "total")), 2);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "total_relation")), "eq");
+    yyjson_doc_free(doc);
     free(inner);
     free(response);
     cbm_mcp_server_free(srv);
-    cleanup_snippet_dir(tmp);
     PASS();
 }
 
-TEST(tool_check_index_coverage_surfaces_lookup_errors) {
-    char tmp[256];
-    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+/* Snapshot pagination binds the effective query identity, store generation,
+ * and the complete ordered materialization. Presentation knobs can change;
+ * graph/query identity and result bytes cannot. */
+TEST(tool_query_graph_cursor_is_lossless_and_snapshot_bound) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
     cbm_store_t *store = cbm_mcp_server_store(srv);
     ASSERT_NOT_NULL(store);
-    cbm_project_t project = {0};
-    ASSERT_EQ(cbm_store_get_project(store, "test-project", &project), CBM_STORE_OK);
-    ASSERT_EQ(write_coverage_meta(store, project.indexed_at, "complete"), CBM_STORE_OK);
-    cbm_project_free_fields(&project);
-    ASSERT_EQ(
-        cbm_store_exec(store, "ALTER TABLE index_coverage RENAME COLUMN detail TO broken_detail;"),
-        CBM_STORE_OK);
-
-    char *response = cbm_mcp_handle_tool(
-        srv, "check_index_coverage",
-        "{\"project\":\"test-project\",\"paths\":[\"main.go\"],\"scopes\":[\".\"]}");
-    ASSERT_NOT_NULL(response);
+    const char *project = "query-cursor";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/query-cursor"), CBM_STORE_OK);
+
+    char *long_file = malloc(3001U);
+    ASSERT_NOT_NULL(long_file);
+    memset(long_file, 'p', 3000U);
+    long_file[3000] = '\0';
+    for (int index = 0; index < 5; index++) {
+        char name[16];
+        char qn[48];
+        snprintf(name, sizeof(name), "row_%d", index);
+        snprintf(qn, sizeof(qn), "query-cursor.row_%d", index);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = name,
+                           .qualified_name = qn,
+                           .file_path = index == 4 ? long_file : "src/short.c",
+                           .start_line = index + 1,
+                           .end_line = index + 1};
+        ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    }
+    const char *query = "MATCH (n:Function) RETURN n.qualified_name AS qn, n.file_path AS file "
+                        "ORDER BY qn";
+
+    char first_args[512];
+    snprintf(first_args, sizeof(first_args),
+             "{\"project\":\"%s\",\"query\":\"%s\",\"max_rows\":2,"
+             "\"max_output_tokens\":2000,\"format\":\"json\"}",
+             project, query);
+    char *response = cbm_mcp_handle_tool(srv, "query_graph", first_args);
     char *inner = extract_text_content(response);
     ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "\"coverage_lookup\":\"error\""));
-    ASSERT_NOT_NULL(strstr(inner, "\"status\":\"coverage_unavailable\""));
-    ASSERT_NULL(strstr(inner, "\"status\":\"no_recorded_issue\""));
-
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *next_value = yyjson_obj_get(root, "next_cursor");
+    ASSERT_TRUE(yyjson_is_str(next_value));
+    char *first_cursor = strdup(yyjson_get_str(next_value));
+    ASSERT_NOT_NULL(first_cursor);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "next_offset")), 2);
+    ASSERT_STR_EQ(
+        yyjson_get_str(yyjson_arr_get(yyjson_arr_get(yyjson_obj_get(root, "rows"), 0), 0)),
+        "query-cursor.row_0");
+    yyjson_doc_free(doc);
     free(inner);
     free(response);
+
+    /* max_rows, output budget, and format are presentation only. */
+    char args[1024];
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"query\":\"%s\",\"max_rows\":2,"
+             "\"max_output_tokens\":1000,\"format\":\"tree\",\"cursor\":\"%s\"}",
+             project, query, first_cursor);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "query-cursor.row_2"));
+    ASSERT_NOT_NULL(strstr(inner, "query-cursor.row_3"));
+    ASSERT_NULL(strstr(inner, "query-cursor.row_0"));
+    const char *cursor_line = strstr(inner, "next_cursor: ");
+    ASSERT_NOT_NULL(cursor_line);
+    cursor_line += strlen("next_cursor: ");
+    size_t second_cursor_len = strcspn(cursor_line, "\r\n");
+    ASSERT_TRUE(second_cursor_len > 0 && second_cursor_len < 224U);
+    char second_cursor[224];
+    memcpy(second_cursor, cursor_line, second_cursor_len);
+    second_cursor[second_cursor_len] = '\0';
+    free(inner);
+    free(response);
+
+    /* The next row exists but cannot fit at the floor. No advancing cursor is
+     * fabricated; retrying the same cursor at a higher budget resumes it. */
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"query\":\"%s\",\"max_rows\":9,"
+             "\"max_output_tokens\":128,\"format\":\"json\",\"cursor\":\"%s\"}",
+             project, query, second_cursor);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 0);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    ASSERT_NULL(yyjson_obj_get(root, "next_cursor"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"query\":\"%s\",\"max_rows\":9,"
+             "\"max_output_tokens\":2000,\"format\":\"json\",\"cursor\":\"%s\"}",
+             project, query, second_cursor);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 1);
+    ASSERT_STR_EQ(
+        yyjson_get_str(yyjson_arr_get(yyjson_arr_get(yyjson_obj_get(root, "rows"), 0), 0)),
+        "query-cursor.row_4");
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* A changed row without a generation bump is still detected by the full
+     * ordered-materialization digest. */
+    cbm_node_t changed = {.project = project,
+                          .label = "Function",
+                          .name = "row_3",
+                          .qualified_name = "query-cursor.row_3",
+                          .file_path = "src/changed.c",
+                          .start_line = 4,
+                          .end_line = 4};
+    ASSERT_GT(cbm_store_upsert_node(store, &changed), 0);
+    snprintf(args, sizeof(args), "{\"project\":\"%s\",\"query\":\"%s\",\"cursor\":\"%s\"}", project,
+             query, first_cursor);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "stale_cursor"));
+    ASSERT_NOT_NULL(strstr(response, "isError"));
+    free(inner);
+    free(response);
+
+    /* Query identity, explicit offsets, cursor bytes, and generation are all
+     * independently fail-closed. */
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"query\":\"MATCH (n) RETURN n.name\","
+             "\"cursor\":\"%s\"}",
+             project, first_cursor);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(strstr(inner, "cursor_params_mismatch"));
+    free(inner);
+    free(response);
+
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"query\":\"%s\",\"offset\":1,"
+             "\"cursor\":\"%s\"}",
+             project, query, first_cursor);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(strstr(inner, "cannot be combined"));
+    free(inner);
+    free(response);
+
+    char *tampered = strdup(first_cursor);
+    ASSERT_NOT_NULL(tampered);
+    size_t tampered_len = strlen(tampered);
+    tampered[tampered_len - 1U] = tampered[tampered_len - 1U] == '0' ? '1' : '0';
+    snprintf(args, sizeof(args), "{\"project\":\"%s\",\"query\":\"%s\",\"cursor\":\"%s\"}", project,
+             query, tampered);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(strstr(inner, "invalid_cursor"));
+    free(inner);
+    free(response);
+    free(tampered);
+
+    /* Mint under the changed materialization, then invalidate by generation. */
+    response = cbm_mcp_handle_tool(srv, "query_graph", first_args);
+    inner = extract_text_content(response);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    next_value = yyjson_obj_get(yyjson_doc_get_root(doc), "next_cursor");
+    ASSERT_TRUE(yyjson_is_str(next_value));
+    char *generation_cursor = strdup(yyjson_get_str(next_value));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+    ASSERT_NOT_NULL(generation_cursor);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/query-cursor"), CBM_STORE_OK);
+    snprintf(args, sizeof(args), "{\"project\":\"%s\",\"query\":\"%s\",\"cursor\":\"%s\"}", project,
+             query, generation_cursor);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(strstr(inner, "stale_cursor"));
+    free(inner);
+    free(response);
+
+    /* Corrupt generation metadata must not silently degrade a fresh request
+     * to mutation-unsafe raw-offset pagination. */
+    ASSERT_EQ(cbm_store_exec(store, "UPDATE store_meta SET v='not-a-number' "
+                                    "WHERE k='mutation_gen';"),
+              CBM_STORE_OK);
+    response = cbm_mcp_handle_tool(srv, "query_graph", first_args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "index_metadata_error"));
+    ASSERT_NOT_NULL(strstr(response, "isError"));
+    free(inner);
+    free(response);
+
+    free(generation_cursor);
+    free(first_cursor);
+    free(long_file);
     cbm_mcp_server_free(srv);
-    cleanup_snippet_dir(tmp);
     PASS();
 }
 
-TEST(tool_index_status_includes_git_metadata) {
-    /* The git context block moved behind verbose:true (lean-default contract,
-     * TOON round 2) — this test pins the verbose path's content; the default-
-     * omission guard lives in tool_lean_defaults_schema_and_status. */
-    char tmp[256];
-    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+TEST(tool_query_graph_budget_bounds_first_row_and_json_escaping) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "query-wide-row";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/query-wide-row"), CBM_STORE_OK);
 
-    char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":16,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"index_status\","
-             "\"arguments\":{\"project\":\"test-project\",\"verbose\":true}}}");
-    ASSERT_NOT_NULL(resp);
-    char *inner = extract_text_content(resp);
-    ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "\"root_path\""));
-    ASSERT_NOT_NULL(strstr(inner, "\"git\""));
-    ASSERT_NOT_NULL(strstr(inner, "\"is_git\":false"));
-    ASSERT_NOT_NULL(strstr(inner, "\"root_exists\":true"));
+    char large[5001];
+    for (int i = 0; i < 5000; i++) {
+        large[i] = i % 2 == 0 ? '\\' : '"';
+    }
+    large[5000] = '\0';
+    cbm_node_t node = {.project = project,
+                       .label = "Function",
+                       .name = large,
+                       .qualified_name = "query-wide-row.wide",
+                       .file_path = "wide.c"};
+    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+
+    const char *formats[] = {"tree", "json"};
+    for (int i = 0; i < 2; i++) {
+        char args[384];
+        snprintf(args, sizeof(args),
+                 "{\"project\":\"%s\",\"query\":\"MATCH (n) RETURN n.name\","
+                 "\"format\":\"%s\",\"max_output_tokens\":128}",
+                 project, formats[i]);
+        char *response = cbm_mcp_handle_tool(srv, "query_graph", args);
+        char *inner = extract_text_content(response);
+        ASSERT_NOT_NULL(inner);
+        ASSERT_LTE((int)strlen(inner), 512);
+        if (strcmp(formats[i], "json") == 0) {
+            yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+            ASSERT_NOT_NULL(doc);
+            yyjson_val *root = yyjson_doc_get_root(doc);
+            ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 0);
+            ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+            ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "truncation_reason")),
+                          "output_budget");
+            yyjson_doc_free(doc);
+        } else {
+            ASSERT_NOT_NULL(strstr(inner, "returned: 0"));
+            ASSERT_NOT_NULL(strstr(inner, "truncation_reason: output_budget"));
+        }
+        free(inner);
+        free(response);
+    }
 
+    /* Query expressions are response metadata too. A pathological alias must
+     * not bypass the budget when zero rows fit, and must never be byte-sliced
+     * into a false column name. */
+    char alias[5001];
+    memset(alias, 'a', sizeof(alias) - 1);
+    alias[sizeof(alias) - 1] = '\0';
+    char wide_query_args[5500];
+    snprintf(wide_query_args, sizeof(wide_query_args),
+             "{\"project\":\"%s\",\"query\":\"MATCH (n) RETURN n.name AS %s\","
+             "\"format\":\"json\",\"max_output_tokens\":128}",
+             project, alias);
+    char *response = cbm_mcp_handle_tool(srv, "query_graph", wide_query_args);
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_LTE((int)strlen(inner), 512);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "columns_omitted")));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "returned")), 0);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "truncation_reason")), "output_budget");
+    yyjson_doc_free(doc);
     free(inner);
-    free(resp);
+    free(response);
+
     cbm_mcp_server_free(srv);
-    cleanup_snippet_dir(tmp);
     PASS();
 }
 
-/* ══════════════════════════════════════════════════════════════════
- *  TOOL HANDLERS WITH DATA
- * ══════════════════════════════════════════════════════════════════ */
-
-TEST(tool_trace_call_path_not_found) {
+TEST(tool_query_graph_prefix_directory_is_lossless_and_json_stays_direct) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "prefix-directory";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/prefix-directory"), CBM_STORE_OK);
+    for (int i = 0; i < 24; i++) {
+        char name[32];
+        char qualified_name[128];
+        snprintf(name, sizeof(name), "function_%03d", i);
+        snprintf(qualified_name, sizeof(qualified_name), "prefix-directory.src.deep.module.%s",
+                 name);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = name,
+                           .qualified_name = qualified_name,
+                           .file_path = "src/deep/module/shared_file.c",
+                           .start_line = i + 1,
+                           .end_line = i + 1};
+        ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    }
+
+    const char *query = "MATCH (n:Function) RETURN n.qualified_name AS qn, n.file_path AS file "
+                        "ORDER BY n.qualified_name";
+    char args[512];
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"query\":\"%s\",\"max_output_tokens\":20000}", project, query);
+    char *response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    ASSERT_NOT_NULL(response);
+    ASSERT_NULL(strstr(response, "structuredContent"));
+    char *tree = extract_text_content(response);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NOT_NULL(strstr(tree, "rows_refs:"));
+    ASSERT_NOT_NULL(strstr(tree, "rows_ref_rule: @N+suffix=prefix+suffix"));
+    ASSERT_NOT_NULL(strstr(tree, "prefix-directory.src.deep.module."));
+    ASSERT_NOT_NULL(strstr(tree, "src/deep/module/shared_file.c"));
+    ASSERT_NOT_NULL(strstr(tree, "returned: 24"));
+    ASSERT_NOT_NULL(strstr(tree, "total_relation: eq"));
+
+    /* Decode one representative reference from the wire text. Its prefix plus
+     * suffix must reproduce the direct qualified name byte-for-byte. */
+    const char *suffix = strstr(tree, "+function_000");
+    ASSERT_NOT_NULL(suffix);
+    const char *token = suffix;
+    while (token > tree && token[-1] != ' ' && token[-1] != '\n') {
+        token--;
+    }
+    ASSERT_EQ(*token, '@');
+    char *id_end = NULL;
+    long ref_id = strtol(token + 1, &id_end, 10);
+    ASSERT_NOT_NULL(id_end);
+    ASSERT_EQ(*id_end, '+');
+    char map_needle[32];
+    snprintf(map_needle, sizeof(map_needle), "\n  %ld ", ref_id);
+    const char *map = strstr(tree, map_needle);
+    ASSERT_NOT_NULL(map);
+    const char *prefix = map + strlen(map_needle);
+    const char *prefix_end = strchr(prefix, '\n');
+    ASSERT_NOT_NULL(prefix_end);
+    size_t prefix_len = (size_t)(prefix_end - prefix);
+    size_t suffix_len = strcspn(id_end + 1, " \n");
+    char reconstructed[160];
+    ASSERT_TRUE(prefix_len + suffix_len < sizeof(reconstructed));
+    memcpy(reconstructed, prefix, prefix_len);
+    memcpy(reconstructed + prefix_len, id_end + 1, suffix_len);
+    reconstructed[prefix_len + suffix_len] = '\0';
+    ASSERT_STR_EQ(reconstructed, "prefix-directory.src.deep.module.function_000");
+    free(tree);
+    free(response);
 
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":20,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"trace_call_path\","
-                                   "\"arguments\":{\"function_name\":\"NonExistent\","
-                                   "\"project\":\"nonexistent\"}}}");
-    ASSERT_NOT_NULL(resp);
-    /* Should return error about project not found */
-    ASSERT_NOT_NULL(strstr(resp, "not found"));
-    free(resp);
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"query\":\"%s\",\"format\":\"json\","
+             "\"max_output_tokens\":20000}",
+             project, query);
+    response = cbm_mcp_handle_tool(srv, "query_graph", args);
+    ASSERT_NOT_NULL(response);
+    tree = extract_text_content(response);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NULL(strstr(tree, "rows_refs"));
+    yyjson_doc *doc = yyjson_read(tree, strlen(tree), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *rows = yyjson_obj_get(yyjson_doc_get_root(doc), "rows");
+    ASSERT_EQ(yyjson_arr_size(rows), 24);
+    yyjson_val *first = yyjson_arr_get_first(rows);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(first, 0)), reconstructed);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(first, 1)), "src/deep/module/shared_file.c");
+    yyjson_doc_free(doc);
+    free(tree);
+    free(response);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_query_graph_prefix_directory_recovers_rows_beyond_raw_estimate) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "prefix-large-shared-root";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/prefix-large-shared-root"),
+              CBM_STORE_OK);
 
+    enum { PREFIX_CAP = 4096, NODE_COUNT = 200 };
+    char *prefix = malloc(PREFIX_CAP);
+    ASSERT_NOT_NULL(prefix);
+    size_t prefix_len = 0;
+    while (prefix_len + sizeof("verylongsegment.") < 3000U) {
+        memcpy(prefix + prefix_len, "verylongsegment.", sizeof("verylongsegment.") - 1U);
+        prefix_len += sizeof("verylongsegment.") - 1U;
+    }
+    prefix[prefix_len] = '\0';
+    for (int i = 0; i < NODE_COUNT; i++) {
+        char name[32];
+        snprintf(name, sizeof(name), "function_%03d", i);
+        size_t qn_cap = prefix_len + strlen(name) + 1U;
+        char *qualified_name = malloc(qn_cap);
+        ASSERT_NOT_NULL(qualified_name);
+        snprintf(qualified_name, qn_cap, "%s%s", prefix, name);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = name,
+                           .qualified_name = qualified_name,
+                           .file_path = "src/shared.c",
+                           .start_line = i + 1,
+                           .end_line = i + 1};
+        ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+        free(qualified_name);
+    }
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "query_graph",
+                            "{\"project\":\"prefix-large-shared-root\","
+                            "\"query\":\"MATCH (n:Function) RETURN n.qualified_name AS qn ORDER BY "
+                            "n.qualified_name\"}");
+    char *tree = extract_text_content(response);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_LTE(strlen(tree), 3200U * 4U);
+    ASSERT_NOT_NULL(strstr(tree, "rows_refs:"));
+    ASSERT_NOT_NULL(strstr(tree, prefix));
+    ASSERT_NOT_NULL(strstr(tree, "returned: 200"));
+    ASSERT_NOT_NULL(strstr(tree, "+function_199"));
+
+    free(tree);
+    free(response);
+    free(prefix);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Regression for #1425: a project name that fails validation must produce a
- * clean "not found" error and NOTHING else. project_db_path() yields "" for
- * such names; SQLite opens "" as an anonymous temp db, its integrity check
- * fails, and quarantine rendered "".corrupt.<hex> - a RELATIVE path dropped
- * into the daemon's cwd on every such query. */
-TEST(tool_call_invalid_project_name_leaves_no_corrupt_litter_issue1425) {
-    char tmpdir[256];
-    snprintf(tmpdir, sizeof(tmpdir), "/tmp/mcp-litter-XXXXXX");
-    if (!cbm_mkdtemp(tmpdir))
-        FAIL("cbm_mkdtemp failed");
-    char oldcwd[CBM_SZ_1K];
-    if (!cbm_getcwd(oldcwd, sizeof(oldcwd)))
-        FAIL("getcwd failed");
-    if (cbm_chdir(tmpdir) != 0)
-        FAIL("chdir failed");
+TEST(tool_list_projects_tree_uses_one_stable_header_and_keeps_json_direct) {
+    char cache[256];
+    snprintf(cache, sizeof(cache), "%s/cbm-list-lean-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    cbm_setenv("CBM_CACHE_DIR", cache, 1);
+
+    enum { PROJECTS = 12 };
+    for (int i = 0; i < PROJECTS; i++) {
+        char project[32];
+        char db_path[512];
+        char root_path[512];
+        snprintf(project, sizeof(project), "lean-project-%02d", i);
+        snprintf(db_path, sizeof(db_path), "%s/%s.db", cache, project);
+        snprintf(root_path, sizeof(root_path),
+                 "/workspaces/organization/shared/services/lean-project-%02d", i);
+        cbm_store_t *store = cbm_store_open_path(db_path);
+        ASSERT_NOT_NULL(store);
+        ASSERT_EQ(cbm_store_upsert_project(store, project, root_path), CBM_STORE_OK);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = "entry",
+                           .qualified_name = "shared.module.entry",
+                           .file_path = "src/main.c",
+                           .start_line = 1,
+                           .end_line = 1};
+        ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+        cbm_store_close(store);
+    }
 
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":30,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"search_graph\","
-                                   "\"arguments\":{\"name_pattern\":\"x\","
-                                   "\"project\":\"bad name\"}}}");
-    bool clean_error = resp && strstr(resp, "not found") != NULL;
-    free(resp);
-    cbm_mcp_server_free(srv);
+    ASSERT_NOT_NULL(srv);
+    char *identity_response = cbm_mcp_handle_tool(srv, "list_projects", "{\"limit\":50}");
+    char *identity = extract_text_content(identity_response);
+    char *tree_response =
+        cbm_mcp_handle_tool(srv, "list_projects", "{\"limit\":50,\"detail\":\"stats\"}");
+    char *tree = extract_text_content(tree_response);
+    char *json_response = cbm_mcp_handle_tool(
+        srv, "list_projects", "{\"limit\":50,\"format\":\"json\",\"detail\":\"stats\"}");
+    char *json = extract_text_content(json_response);
+    char *page_response = cbm_mcp_handle_tool(srv, "list_projects", "{\"limit\":5}");
+    char *page = extract_text_content(page_response);
+
+    bool tree_shape =
+        tree && strstr(tree, "projects_refs:") &&
+        strstr(tree, "projects: 12  (cols: name root_path branch nodes edges size_bytes)") &&
+        strstr(tree, "lean-project-00") && strstr(tree, "lean-project-11") &&
+        strstr(tree, "total: 12") && strstr(tree, "returned: 12") &&
+        strstr(tree, "has_more: false") && !strstr(tree, "\"name\":");
+    bool identity_lean = identity && strstr(identity, "projects_refs:") &&
+                         strstr(identity, "projects: 12  (cols: name root_path branch)") &&
+                         !strstr(identity, "size_bytes") && !strstr(identity, " nodes edges");
+    bool tree_is_leaner = tree && json && strlen(tree) < strlen(json);
+    bool tree_not_duplicated = tree_response && !strstr(tree_response, "structuredContent");
+    bool page_truthful = page && strstr(page, "projects: 5") && strstr(page, "returned: 5") &&
+                         strstr(page, "has_more: true") && strstr(page, "next_offset: 5");
+    bool json_direct = false;
+    bool json_structured = json_response && strstr(json_response, "structuredContent");
+    yyjson_doc *doc = json ? yyjson_read(json, strlen(json), 0) : NULL;
+    if (doc) {
+        yyjson_val *projects = yyjson_obj_get(yyjson_doc_get_root(doc), "projects");
+        yyjson_val *first = projects ? yyjson_arr_get_first(projects) : NULL;
+        json_direct = projects && yyjson_arr_size(projects) == PROJECTS && first &&
+                      yyjson_obj_get(first, "name") && yyjson_obj_get(first, "root_path") &&
+                      yyjson_obj_get(first, "nodes") && yyjson_obj_get(first, "edges") &&
+                      yyjson_obj_get(first, "size_bytes") && !strstr(json, "rows_refs");
+        yyjson_doc_free(doc);
+    }
 
-    int litter = 0;
-    cbm_dir_t *dir = cbm_opendir(tmpdir);
-    if (dir) {
-        cbm_dirent_t *entry;
-        while ((entry = cbm_readdir(dir)) != NULL) {
-            if (strstr(entry->name, ".corrupt.")) {
-                litter++;
-            }
-        }
-        cbm_closedir(dir);
+    free(identity);
+    free(identity_response);
+    free(tree);
+    free(tree_response);
+    free(json);
+    free(json_response);
+    free(page);
+    free(page_response);
+    cbm_mcp_server_free(srv);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    for (int i = 0; i < PROJECTS; i++) {
+        char project[32];
+        snprintf(project, sizeof(project), "lean-project-%02d", i);
+        cleanup_project_db(cache, project);
     }
-    if (cbm_chdir(oldcwd) != 0)
-        FAIL("chdir back failed");
-    th_rmtree(tmpdir);
-    if (!clean_error)
-        FAIL("invalid project name must produce a clean not-found error");
-    if (litter != 0)
-        FAIL("invalid project name must not quarantine an anonymous temp db into cwd (#1425)");
+    cbm_rmdir(cache);
+
+    ASSERT_TRUE(tree_shape);
+    ASSERT_TRUE(identity_lean);
+    ASSERT_TRUE(tree_is_leaner);
+    ASSERT_TRUE(tree_not_duplicated);
+    ASSERT_TRUE(page_truthful);
+    ASSERT_TRUE(json_direct);
+    ASSERT_TRUE(json_structured);
     PASS();
 }
 
-TEST(tool_trace_missing_function_name) {
+/* The stored project root is dynamic identity, not a display-sized field.
+ * Keep a syntactically valid segmented path beyond 1 KiB intact in both wire
+ * encodings; the default detail also routes that same value through branch
+ * discovery before emission. */
+TEST(tool_list_projects_preserves_root_beyond_one_kib) {
+    char cache[256];
+    snprintf(cache, sizeof(cache), "%s/cbm-list-long-root-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    cbm_setenv("CBM_CACHE_DIR", cache, 1);
+
+    enum { ROOT_CAP = 1536 };
+    char *long_root = malloc(ROOT_CAP);
+    ASSERT_NOT_NULL(long_root);
+    size_t root_len = 0;
+    const char root_start[] = "/tmp";
+    const char segment[] = "/segment";
+    const char tail[] = "/lossless-tail";
+    memcpy(long_root, root_start, sizeof(root_start) - 1U);
+    root_len = sizeof(root_start) - 1U;
+    while (root_len + sizeof(segment) - 1U + sizeof(tail) < ROOT_CAP) {
+        memcpy(long_root + root_len, segment, sizeof(segment) - 1U);
+        root_len += sizeof(segment) - 1U;
+    }
+    memcpy(long_root + root_len, tail, sizeof(tail));
+    root_len += sizeof(tail) - 1U;
+    ASSERT_TRUE(root_len > 1024U);
+
+    const char *project = "long-root-project";
+    const char *db_file = "long-root-record";
+    char db_path[512];
+    snprintf(db_path, sizeof(db_path), "%s/%s.db", cache, db_file);
+    cbm_store_t *store = cbm_store_open_path(db_path);
+    ASSERT_NOT_NULL(store);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, long_root), CBM_STORE_OK);
+    cbm_node_t node = {.project = project,
+                       .label = "Function",
+                       .name = "entry",
+                       .qualified_name = "long.root.entry",
+                       .file_path = "src/main.c",
+                       .start_line = 1,
+                       .end_line = 1};
+    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    cbm_store_close(store);
+
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    char *tree_response = cbm_mcp_handle_tool(srv, "list_projects", "{\"limit\":50}");
+    char *tree = extract_text_content(tree_response);
+    ASSERT_NOT_NULL(tree);
+    const char *tree_root = strstr(tree, long_root);
+    ASSERT_NOT_NULL(tree_root);
+    ASSERT_EQ(tree_root[root_len], ' ');
+    ASSERT_NOT_NULL(strstr(tree_root, "/lossless-tail"));
+
+    char *json_response =
+        cbm_mcp_handle_tool(srv, "list_projects", "{\"limit\":50,\"format\":\"json\"}");
+    char *json = extract_text_content(json_response);
+    ASSERT_NOT_NULL(json);
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *projects = yyjson_obj_get(yyjson_doc_get_root(doc), "projects");
+    ASSERT_NOT_NULL(projects);
+    ASSERT_EQ(yyjson_arr_size(projects), 1);
+    yyjson_val *listed = yyjson_arr_get_first(projects);
+    const char *listed_root = yyjson_get_str(yyjson_obj_get(listed, "root_path"));
+    ASSERT_NOT_NULL(listed_root);
+    ASSERT_EQ(strlen(listed_root), root_len);
+    ASSERT_STR_EQ(listed_root, long_root);
+
+    yyjson_doc_free(doc);
+    free(json);
+    free(json_response);
+    free(tree);
+    free(tree_response);
+    cbm_mcp_server_free(srv);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    cleanup_project_db(cache, db_file);
+    cbm_rmdir(cache);
+    free(long_root);
+    PASS();
+}
+
+TEST(tool_index_status_no_project) {
+    cbm_mcp_server_t *srv = setup_mcp_with_data();
 
     char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":21,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"trace_call_path\","
-                                   "\"arguments\":{}}}");
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":15,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"index_status\",\"arguments\":{}}}");
     ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "required"));
+    /* Should return error or empty status */
+    ASSERT_NOT_NULL(strstr(resp, "\"result\""));
     free(resp);
 
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Regression: two same-named definitions with equal rank must be reported
- * ambiguous, not silently traced (trace_path previously took nodes[0]). */
-TEST(tool_trace_call_path_ambiguous) {
+/* Reproduce the exact-file false negative in the current Read hook: index_status
+ * intentionally caps each coverage category at 500 entries, so a later path is
+ * absent even though the authoritative index_coverage table contains it.  The
+ * targeted coverage tool must query that table rather than scan the capped
+ * presentation response. */
+TEST(tool_check_index_coverage_finds_path_beyond_status_cap) {
+    enum { ROW_COUNT = 502 };
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
     cbm_store_t *st = cbm_mcp_server_store(srv);
-    const char *proj = "amb-proj";
-    cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/amb");
-    cbm_node_t a = {.project = proj,
-                    .label = "Function",
-                    .name = "amb",
-                    .qualified_name = "amb-proj.a.amb",
-                    .file_path = "a.c",
-                    .start_line = 10,
-                    .end_line = 20};
-    cbm_node_t b = {.project = proj,
-                    .label = "Function",
-                    .name = "amb",
-                    .qualified_name = "amb-proj.b.amb",
-                    .file_path = "b.c",
-                    .start_line = 10,
-                    .end_line = 20}; /* equal span -> genuine tie */
-    ASSERT_GT(cbm_store_upsert_node(st, &a), 0);
-    ASSERT_GT(cbm_store_upsert_node(st, &b), 0);
+    ASSERT_NOT_NULL(st);
 
-    char *resp = cbm_mcp_server_handle(
+    const char *project = "coverage-cap-regression";
+    ASSERT_EQ(cbm_store_upsert_project(st, project, "/tmp/coverage-cap-regression"), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
+
+    char (*paths)[64] = calloc(ROW_COUNT, sizeof(*paths));
+    cbm_coverage_row_t *rows = calloc(ROW_COUNT, sizeof(*rows));
+    ASSERT_NOT_NULL(paths);
+    ASSERT_NOT_NULL(rows);
+    for (int i = 0; i < ROW_COUNT; i++) {
+        snprintf(paths[i], sizeof(paths[i]), "src/partial-%04d.c", i);
+        rows[i].rel_path = paths[i];
+        rows[i].kind = "parse_partial";
+        rows[i].detail = i == ROW_COUNT - 1 ? "777-790" : "1-2";
+        ASSERT_EQ(cbm_store_upsert_file_hash(st, project, paths[i], "fixture", i + 1, 10),
+                  CBM_STORE_OK);
+    }
+    ASSERT_EQ(cbm_store_coverage_replace(st, project, rows, ROW_COUNT), CBM_STORE_OK);
+
+    char *status = cbm_mcp_handle_tool(
+        srv, "index_status",
+        "{\"project\":\"coverage-cap-regression\",\"diagnostics\":\"full\",\"format\":\"json\"}");
+    ASSERT_NOT_NULL(status);
+    char *status_inner = extract_text_content(status);
+    ASSERT_NOT_NULL(status_inner);
+    ASSERT_NOT_NULL(strstr(status_inner, "\"truncated\":true"));
+    ASSERT_NULL(strstr(status_inner, "src/partial-0501.c"));
+    free(status_inner);
+    free(status);
+
+    char *coverage = cbm_mcp_handle_tool(
+        srv, "check_index_coverage",
+        "{\"project\":\"coverage-cap-regression\",\"paths\":[\"src/partial-0501.c\"],"
+        "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(coverage);
+    char *coverage_inner = extract_text_content(coverage);
+    ASSERT_NOT_NULL(coverage_inner);
+    ASSERT_NOT_NULL(strstr(coverage_inner, "src/partial-0501.c"));
+    ASSERT_NOT_NULL(strstr(coverage_inner, "\"status\":\"partial\""));
+    ASSERT_NOT_NULL(strstr(coverage_inner, "\"start\":777"));
+    ASSERT_NOT_NULL(strstr(coverage_inner, "\"end\":790"));
+    ASSERT_NULL(strstr(coverage_inner, "\"detail\":\"777-790\""));
+
+    free(coverage_inner);
+    free(coverage);
+    free(rows);
+    free(paths);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_check_index_coverage_pages_exact_paths_and_restores_raw_diagnostics) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "coverage-path-page";
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/coverage-path-page"), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
+    cbm_coverage_row_t row = {
+        .rel_path = "path-00.c", .kind = "parse_partial", .detail = "11-19,27"};
+    ASSERT_EQ(cbm_store_upsert_file_hash(store, project, "path-00.c", "fixture", 1, 1),
+              CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_coverage_replace(store, project, &row, 1), CBM_STORE_OK);
+    cbm_coverage_row_t *stored_rows = NULL;
+    int stored_count = 0;
+    ASSERT_EQ(cbm_store_coverage_get_path(store, project, "path-00.c", &stored_rows, &stored_count),
+              CBM_STORE_OK);
+    ASSERT_EQ(stored_count, 1);
+    cbm_store_free_coverage(stored_rows, stored_count);
+
+    char args[4096];
+    size_t used =
+        (size_t)snprintf(args, sizeof(args), "{\"project\":\"coverage-path-page\",\"paths\":[");
+    for (int i = 0; i < 25; i++) {
+        used += (size_t)snprintf(args + used, sizeof(args) - used, "%s\"path-%02d.c\"",
+                                 i ? "," : "", i);
+    }
+    (void)snprintf(args + used, sizeof(args) - used, "],\"format\":\"json\"}");
+
+    char *response = cbm_mcp_handle_tool(srv, "check_index_coverage", args);
+    ASSERT_NOT_NULL(response);
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "path_total")), 25);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "path_returned")), 20);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "path_has_more")));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "path_next_offset")), 20);
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "paths")), 20);
+    ASSERT_NOT_NULL(strstr(inner, "\"start\":11"));
+    ASSERT_NULL(strstr(inner, "\"detail\":\"11-19,27\""));
+    ASSERT_NULL(strstr(inner, "path-20.c"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    used = (size_t)snprintf(args, sizeof(args), "{\"project\":\"coverage-path-page\",\"paths\":[");
+    for (int i = 0; i < 25; i++) {
+        used += (size_t)snprintf(args + used, sizeof(args) - used, "%s\"path-%02d.c\"",
+                                 i ? "," : "", i);
+    }
+    (void)snprintf(args + used, sizeof(args) - used,
+                   "],\"path_offset\":20,\"diagnostics\":\"full\",\"format\":\"json\"}");
+    response = cbm_mcp_handle_tool(srv, "check_index_coverage", args);
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "path_returned")), 5);
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "path_has_more")));
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "paths")), 5);
+    ASSERT_NOT_NULL(strstr(inner, "path-20.c"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    char *full =
+        cbm_mcp_handle_tool(srv, "check_index_coverage",
+                            "{\"project\":\"coverage-path-page\",\"paths\":[\"path-00.c\"],"
+                            "\"diagnostics\":\"full\",\"format\":\"json\"}");
+    ASSERT_NOT_NULL(full);
+    char *full_inner = extract_text_content(full);
+    ASSERT_NOT_NULL(full_inner);
+    ASSERT_NOT_NULL(strstr(full_inner, "\"detail\":\"11-19,27\""));
+    free(full_inner);
+    free(full);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_check_index_coverage_reports_paths_scopes_and_ranges) {
+    char tmp[256];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(st);
+
+    ASSERT_EQ(cbm_store_upsert_file_hash(st, "test-project", "main.go", "", 0, 0), CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_upsert_file_hash(st, "test-project", "src/skip.c", "", 0, 0), CBM_STORE_OK);
+    cbm_coverage_row_t rows[] = {
+        {.rel_path = "main.go", .kind = "parse_partial", .detail = "3-4,9"},
+        {.rel_path = "generated", .kind = "not_indexed_dir", .detail = "excluded subtree"},
+        {.rel_path = "src/skip.c", .kind = "oversized", .detail = "file exceeds cap"},
+    };
+    ASSERT_EQ(cbm_store_coverage_replace(st, "test-project", rows, 3), CBM_STORE_OK);
+
+    char *coverage =
+        cbm_mcp_handle_tool(srv, "check_index_coverage",
+                            "{\"project\":\"test-project\","
+                            "\"paths\":[\"main.go\",\"generated/pkg/a.c\",\"../escape.c\"],"
+                            "\"scopes\":[\".\"],\"format\":\"json\"}");
+    ASSERT_NOT_NULL(coverage);
+    char *inner = extract_text_content(coverage);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"path\":\"main.go\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"status\":\"partial\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"start\":3"));
+    ASSERT_NOT_NULL(strstr(inner, "\"end\":4"));
+    ASSERT_NOT_NULL(strstr(inner, "\"start\":9"));
+    ASSERT_NOT_NULL(strstr(inner, "generated/pkg/a.c"));
+    ASSERT_NOT_NULL(strstr(inner, "not_indexed_dir"));
+    ASSERT_NOT_NULL(strstr(inner, "outside_project"));
+    ASSERT_NOT_NULL(strstr(inner, "src/skip.c"));
+    ASSERT_NOT_NULL(strstr(inner, "file exceeds cap"));
+    ASSERT_NOT_NULL(strstr(inner, "best_effort"));
+
+    free(inner);
+    free(coverage);
+    cbm_mcp_server_free(srv);
+    cleanup_snippet_dir(tmp);
+    PASS();
+}
+
+TEST(tool_check_index_coverage_preserves_multiple_scope_labels) {
+    char tmp[256];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+
+    char *coverage = cbm_mcp_handle_tool(srv, "check_index_coverage",
+                                         "{\"project\":\"test-project\","
+                                         "\"scopes\":[\"alpha/one\",\"bravo/two\",\"charl/tri\"],"
+                                         "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(coverage);
+    char *inner = extract_text_content(coverage);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *scopes = yyjson_obj_get(yyjson_doc_get_root(doc), "scopes");
+    ASSERT_NOT_NULL(scopes);
+    ASSERT_TRUE(yyjson_is_arr(scopes));
+    ASSERT_EQ(yyjson_arr_size(scopes), 3);
+
+    const char *expected[] = {"alpha/one", "bravo/two", "charl/tri"};
+    for (size_t i = 0; i < 3; i++) {
+        yyjson_val *scope = yyjson_obj_get(yyjson_arr_get(scopes, i), "scope");
+        ASSERT_NOT_NULL(scope);
+        ASSERT_TRUE(yyjson_is_str(scope));
+        ASSERT_STR_EQ(yyjson_get_str(scope), expected[i]);
+    }
+
+    yyjson_doc_free(doc);
+    free(inner);
+    free(coverage);
+    cbm_mcp_server_free(srv);
+    cleanup_snippet_dir(tmp);
+    PASS();
+}
+
+static int write_coverage_meta(cbm_store_t *store, const char *generation,
+                               const char *recording_status) {
+    cbm_coverage_meta_t meta = {
+        .generation = generation,
+        .index_mode = "fast",
+        .recorded_at = "2026-07-12T00:00:00Z",
+        .recording_status = recording_status,
+        .ignored_files_stored = 0,
+        .ignored_files_total = 0,
+        .coverage_version = 1,
+        .hash_records_complete = true,
+    };
+    return cbm_store_coverage_replace_ex(store, "test-project", NULL, 0, &meta);
+}
+
+TEST(tool_check_index_coverage_rejects_stale_generation) {
+    char tmp[256];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    ASSERT_EQ(write_coverage_meta(store, "stale-generation", "complete"), CBM_STORE_OK);
+
+    char *response = cbm_mcp_handle_tool(srv, "check_index_coverage",
+                                         "{\"project\":\"test-project\",\"paths\":[\"main.go\"],"
+                                         "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"generation_matches\":false"));
+    ASSERT_NOT_NULL(strstr(inner, "\"status\":\"coverage_unavailable\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"recommended_action\":\"read_source_and_reindex\""));
+
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    cleanup_snippet_dir(tmp);
+    PASS();
+}
+
+TEST(tool_check_index_coverage_requires_source_when_file_metadata_changed) {
+    char tmp[256];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    cbm_project_t project = {0};
+    ASSERT_EQ(cbm_store_get_project(store, "test-project", &project), CBM_STORE_OK);
+    ASSERT_EQ(write_coverage_meta(store, project.indexed_at, "complete"), CBM_STORE_OK);
+    cbm_project_free_fields(&project);
+    ASSERT_EQ(cbm_store_upsert_file_hash(store, "test-project", "main.go", "fixture", 0, 0),
+              CBM_STORE_OK);
+
+    char *response = cbm_mcp_handle_tool(srv, "check_index_coverage",
+                                         "{\"project\":\"test-project\",\"paths\":[\"main.go\"],"
+                                         "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"generation_matches\":true"));
+    ASSERT_NOT_NULL(strstr(inner, "\"freshness\":\"metadata_changed\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"recommended_action\":\"read_source_and_reindex\""));
+
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    cleanup_snippet_dir(tmp);
+    PASS();
+}
+
+TEST(tool_check_index_coverage_surfaces_lookup_errors) {
+    char tmp[256];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    cbm_project_t project = {0};
+    ASSERT_EQ(cbm_store_get_project(store, "test-project", &project), CBM_STORE_OK);
+    ASSERT_EQ(write_coverage_meta(store, project.indexed_at, "complete"), CBM_STORE_OK);
+    cbm_project_free_fields(&project);
+    ASSERT_EQ(
+        cbm_store_exec(store, "ALTER TABLE index_coverage RENAME COLUMN detail TO broken_detail;"),
+        CBM_STORE_OK);
+
+    char *response = cbm_mcp_handle_tool(
+        srv, "check_index_coverage",
+        "{\"project\":\"test-project\",\"paths\":[\"main.go\"],\"scopes\":[\".\"],"
+        "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"coverage_lookup\":\"error\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"status\":\"coverage_unavailable\""));
+    ASSERT_NULL(strstr(inner, "\"status\":\"no_recorded_issue\""));
+
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    cleanup_snippet_dir(tmp);
+    PASS();
+}
+
+TEST(tool_index_status_includes_git_metadata) {
+    /* The git context block moved behind verbose:true (lean-default contract,
+     * TOON round 2) — this test pins the verbose path's content; the default-
+     * omission guard lives in tool_lean_defaults_schema_and_status. */
+    char tmp[256];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":16,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"index_status\","
+                                   "\"arguments\":{\"project\":\"test-project\",\"verbose\":true,"
+                                   "\"format\":\"json\"}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"root_path\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"git\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"is_git\":false"));
+    ASSERT_NOT_NULL(strstr(inner, "\"root_exists\":true"));
+
+    free(inner);
+    free(resp);
+    cbm_mcp_server_free(srv);
+    cleanup_snippet_dir(tmp);
+    PASS();
+}
+
+/* ══════════════════════════════════════════════════════════════════
+ *  TOOL HANDLERS WITH DATA
+ * ══════════════════════════════════════════════════════════════════ */
+
+TEST(tool_trace_call_path_not_found) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":20,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"trace_call_path\","
+                                   "\"arguments\":{\"function_name\":\"NonExistent\","
+                                   "\"project\":\"nonexistent\"}}}");
+    ASSERT_NOT_NULL(resp);
+    /* Should return error about project not found */
+    ASSERT_NOT_NULL(strstr(resp, "not found"));
+    free(resp);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Regression for #1425: a project name that fails validation must produce a
+ * clean "not found" error and NOTHING else. project_db_path() yields "" for
+ * such names; SQLite opens "" as an anonymous temp db, its integrity check
+ * fails, and quarantine rendered "".corrupt.<hex> - a RELATIVE path dropped
+ * into the daemon's cwd on every such query. */
+TEST(tool_call_invalid_project_name_leaves_no_corrupt_litter_issue1425) {
+    char tmpdir[256];
+    snprintf(tmpdir, sizeof(tmpdir), "/tmp/mcp-litter-XXXXXX");
+    if (!cbm_mkdtemp(tmpdir))
+        FAIL("cbm_mkdtemp failed");
+    char oldcwd[CBM_SZ_1K];
+    if (!cbm_getcwd(oldcwd, sizeof(oldcwd)))
+        FAIL("getcwd failed");
+    if (cbm_chdir(tmpdir) != 0)
+        FAIL("chdir failed");
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":30,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"search_graph\","
+                                   "\"arguments\":{\"name_pattern\":\"x\","
+                                   "\"project\":\"bad name\"}}}");
+    bool clean_error = resp && strstr(resp, "not found") != NULL;
+    free(resp);
+    cbm_mcp_server_free(srv);
+
+    int litter = 0;
+    cbm_dir_t *dir = cbm_opendir(tmpdir);
+    if (dir) {
+        cbm_dirent_t *entry;
+        while ((entry = cbm_readdir(dir)) != NULL) {
+            if (strstr(entry->name, ".corrupt.")) {
+                litter++;
+            }
+        }
+        cbm_closedir(dir);
+    }
+    if (cbm_chdir(oldcwd) != 0)
+        FAIL("chdir back failed");
+    th_rmtree(tmpdir);
+    if (!clean_error)
+        FAIL("invalid project name must produce a clean not-found error");
+    if (litter != 0)
+        FAIL("invalid project name must not quarantine an anonymous temp db into cwd (#1425)");
+    PASS();
+}
+
+TEST(tool_trace_missing_function_name) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":21,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"trace_call_path\","
+                                   "\"arguments\":{}}}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "required"));
+    free(resp);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Regression: two same-named definitions with equal rank must be reported
+ * ambiguous, not silently traced (trace_path previously took nodes[0]). */
+TEST(tool_trace_call_path_ambiguous) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "amb-proj";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/amb");
+    cbm_node_t a = {.project = proj,
+                    .label = "Function",
+                    .name = "amb",
+                    .qualified_name = "amb-proj.a.amb",
+                    .file_path = "a.c",
+                    .start_line = 10,
+                    .end_line = 20};
+    cbm_node_t b = {.project = proj,
+                    .label = "Function",
+                    .name = "amb",
+                    .qualified_name = "amb-proj.b.amb",
+                    .file_path = "b.c",
+                    .start_line = 10,
+                    .end_line = 20}; /* equal span -> genuine tie */
+    ASSERT_GT(cbm_store_upsert_node(st, &a), 0);
+    ASSERT_GT(cbm_store_upsert_node(st, &b), 0);
+
+    char *resp = cbm_mcp_server_handle(
         srv, "{\"jsonrpc\":\"2.0\",\"id\":61,\"method\":\"tools/call\","
              "\"params\":{\"name\":\"trace_call_path\","
              "\"arguments\":{\"function_name\":\"amb\",\"project\":\"amb-proj\"}}}");
@@ -2759,482 +5268,1922 @@ TEST(tool_trace_call_path_ambiguous) {
     ASSERT_NOT_NULL(inner);
     ASSERT_NOT_NULL(strstr(inner, "ambiguous"));
     ASSERT_NOT_NULL(strstr(inner, "suggestions"));
-    ASSERT_NULL(strstr(inner, "\"callees\""));
+    ASSERT_NULL(strstr(inner, "\"callees\""));
+    free(inner);
+    free(resp);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Multi-seed union hop semantics: bfs_union_same_name deduped visited nodes
+ * keep-FIRST-seen, so a node reached at hop 2 from the first seed kept hop 2
+ * even when the second seed reaches it at hop 1. hop feeds risk_labels and
+ * (soon) pagination watermarks — it must be the MINIMUM across seeds, matching
+ * the single-BFS MIN(hop) semantics (#797). */
+TEST(tool_trace_union_records_min_hop_across_seeds) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "dualproj";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/dual");
+
+    /* One real definition + one body-less stub (start==end) — the #546/#650
+     * shape pick_resolved_node resolves WITHOUT ambiguity while
+     * bfs_union_same_name still traverses both. Seed A (real def, lower id,
+     * traversed first) reaches tgt only via mid (hop 2); the stub seed B
+     * reaches tgt directly (hop 1). */
+    cbm_node_t sa = {.project = proj,
+                     .label = "Function",
+                     .name = "dual",
+                     .qualified_name = "dualproj.a.dual",
+                     .file_path = "a.c",
+                     .start_line = 1,
+                     .end_line = 50};
+    cbm_node_t sb = {.project = proj,
+                     .label = "Function",
+                     .name = "dual",
+                     .qualified_name = "dualproj.b.dual",
+                     .file_path = "b.d.ts",
+                     .start_line = 1,
+                     .end_line = 1};
+    cbm_node_t mid = {.project = proj,
+                      .label = "Function",
+                      .name = "mid",
+                      .qualified_name = "dualproj.c.mid",
+                      .file_path = "c.c",
+                      .start_line = 1,
+                      .end_line = 5};
+    cbm_node_t tgt = {.project = proj,
+                      .label = "Function",
+                      .name = "tgt",
+                      .qualified_name = "dualproj.c.tgt",
+                      .file_path = "c.c",
+                      .start_line = 10,
+                      .end_line = 15};
+    int64_t ida = cbm_store_upsert_node(st, &sa);
+    int64_t idb = cbm_store_upsert_node(st, &sb);
+    int64_t idm = cbm_store_upsert_node(st, &mid);
+    int64_t idt = cbm_store_upsert_node(st, &tgt);
+    ASSERT_GT(ida, 0);
+    ASSERT_GT(idb, 0);
+    ASSERT_GT(idm, 0);
+    ASSERT_GT(idt, 0);
+    cbm_edge_t e1 = {.project = proj, .source_id = ida, .target_id = idm, .type = "CALLS"};
+    cbm_edge_t e2 = {.project = proj, .source_id = idm, .target_id = idt, .type = "CALLS"};
+    cbm_edge_t e3 = {.project = proj, .source_id = idb, .target_id = idt, .type = "CALLS"};
+    ASSERT_GT(cbm_store_insert_edge(st, &e1), 0);
+    ASSERT_GT(cbm_store_insert_edge(st, &e2), 0);
+    ASSERT_GT(cbm_store_insert_edge(st, &e3), 0);
+
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":62,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"trace_call_path\","
+             "\"arguments\":{\"function_name\":\"dual\",\"project\":\"dualproj\","
+             "\"direction\":\"outbound\",\"depth\":3}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    /* tgt is one hop from seed B — the union must record hop 1, not seed A's 2. */
+    ASSERT_NOT_NULL(strstr(inner, "dualproj.c.tgt 1"));
+    ASSERT_NULL(strstr(inner, "dualproj.c.tgt 2"));
+    free(inner);
+    free(resp);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Exactly-once trace pagination: 12 callees paged at limit=5 must yield
+ * 5+5+2 rows with every callee appearing on exactly one page, exact totals
+ * on every page, and a final page without a cursor. Stale and mismatched
+ * cursors must fail with teaching errors, never silently restart. */
+TEST(tool_trace_pagination_exactly_once) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "pageproj";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/page");
+
+    cbm_node_t hub = {.project = proj,
+                      .label = "Function",
+                      .name = "hub",
+                      .qualified_name = "pageproj.h.hub",
+                      .file_path = "h.c",
+                      .start_line = 1,
+                      .end_line = 9};
+    int64_t hid = cbm_store_upsert_node(st, &hub);
+    ASSERT_GT(hid, 0);
+    enum { CALLEES = 12 };
+    for (int i = 0; i < CALLEES; i++) {
+        char nm[16];
+        char qn[48];
+        snprintf(nm, sizeof(nm), "c%02d", i);
+        snprintf(qn, sizeof(qn), "pageproj.m.c%02d", i);
+        cbm_node_t n = {.project = proj,
+                        .label = "Function",
+                        .name = nm,
+                        .qualified_name = qn,
+                        .file_path = "m.c",
+                        .start_line = 1,
+                        .end_line = 3};
+        int64_t nid = cbm_store_upsert_node(st, &n);
+        ASSERT_GT(nid, 0);
+        cbm_edge_t e = {.project = proj, .source_id = hid, .target_id = nid, .type = "CALLS"};
+        ASSERT_GT(cbm_store_insert_edge(st, &e), 0);
+    }
+
+    char pages[3][4096];
+    char tok[192] = "";
+    int npages = 0;
+    for (; npages < 3; npages++) {
+        char req[640];
+        if (tok[0]) {
+            snprintf(req, sizeof(req),
+                     "{\"jsonrpc\":\"2.0\",\"id\":80,\"method\":\"tools/call\",\"params\":{"
+                     "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
+                     "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,"
+                     "\"cursor\":\"%s\"}}}",
+                     tok);
+        } else {
+            snprintf(req, sizeof(req),
+                     "{\"jsonrpc\":\"2.0\",\"id\":80,\"method\":\"tools/call\",\"params\":{"
+                     "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
+                     "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5}}}");
+        }
+        char *resp = cbm_mcp_server_handle(srv, req);
+        ASSERT_NOT_NULL(resp);
+        char *inner = extract_text_content(resp);
+        free(resp);
+        ASSERT_NOT_NULL(inner);
+        snprintf(pages[npages], sizeof(pages[npages]), "%s", inner);
+        ASSERT_NOT_NULL(strstr(inner, "callees_total: 12")); /* exact total, every page */
+        const char *nx = strstr(inner, "next: ");
+        if (nx) {
+            const char *e = strchr(nx + 6, '\n');
+            size_t tl = e ? (size_t)(e - (nx + 6)) : strlen(nx + 6);
+            ASSERT_TRUE(tl < sizeof(tok));
+            memcpy(tok, nx + 6, tl);
+            tok[tl] = '\0';
+        } else {
+            tok[0] = '\0';
+        }
+        free(inner);
+        if (!tok[0]) {
+            npages++;
+            break;
+        }
+    }
+    ASSERT_EQ(npages, 3); /* 5 + 5 + 2 */
+    /* Exactly-once: every callee appears on exactly ONE page. */
+    for (int i = 0; i < CALLEES; i++) {
+        char qn[48];
+        snprintf(qn, sizeof(qn), "pageproj.m.c%02d 1\n", i);
+        int seen = 0;
+        for (int p = 0; p < 3; p++) {
+            if (strstr(pages[p], qn)) {
+                seen++;
+            }
+        }
+        ASSERT_EQ(seen, 1);
+    }
+    /* Final page carries no cursor. */
+    ASSERT_NULL(strstr(pages[2], "next: "));
+
+    /* Params mismatch: replay a page-2-era cursor with a different depth. */
+    const char *nx1 = strstr(pages[0], "next: ");
+    ASSERT_NOT_NULL(nx1);
+    char tok1[192];
+    const char *e1 = strchr(nx1 + 6, '\n');
+    size_t tl1 = e1 ? (size_t)(e1 - (nx1 + 6)) : strlen(nx1 + 6);
+    memcpy(tok1, nx1 + 6, tl1);
+    tok1[tl1] = '\0';
+    char req2[640];
+    snprintf(req2, sizeof(req2),
+             "{\"jsonrpc\":\"2.0\",\"id\":81,\"method\":\"tools/call\",\"params\":{"
+             "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
+             "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,\"depth\":2,"
+             "\"cursor\":\"%s\"}}}",
+             tok1);
+    char *resp = cbm_mcp_server_handle(srv, req2);
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    free(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "cursor_params_mismatch"));
+    free(inner);
+
+    /* Corrupt/trailing cursor bytes are rejected exactly, never accepted by a
+     * permissive numeric parse that resumes from an attacker-chosen suffix. */
+    snprintf(req2, sizeof(req2),
+             "{\"jsonrpc\":\"2.0\",\"id\":83,\"method\":\"tools/call\",\"params\":{"
+             "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
+             "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,"
+             "\"cursor\":\"%sjunk\"}}}",
+             tok1);
+    resp = cbm_mcp_server_handle(srv, req2);
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    free(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "invalid_cursor"));
+    free(inner);
+
+    /* The leg is part of the continuation state, not a caller-editable hint.
+     * Flipping an outbound token to inbound must fail for an outbound query. */
+    char tampered[192];
+    snprintf(tampered, sizeof(tampered), "%s", tok1);
+    ASSERT_EQ(tampered[3], 'o');
+    tampered[3] = 'i';
+    snprintf(req2, sizeof(req2),
+             "{\"jsonrpc\":\"2.0\",\"id\":84,\"method\":\"tools/call\",\"params\":{"
+             "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
+             "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,"
+             "\"cursor\":\"%s\"}}}",
+             tampered);
+    resp = cbm_mcp_server_handle(srv, req2);
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    free(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "invalid_cursor"));
+    free(inner);
+
+    /* A validly encoded watermark must be one the server actually emitted in
+     * the selected visible leg; a changed node id cannot act as an arbitrary
+     * insertion point. */
+    const char *node_sep = strrchr(tok1, '.');
+    ASSERT_NOT_NULL(node_sep);
+    size_t prefix_len = (size_t)(node_sep - tok1) + 1U;
+    snprintf(tampered, sizeof(tampered), "%.*s9223372036854775807", (int)prefix_len, tok1);
+    snprintf(req2, sizeof(req2),
+             "{\"jsonrpc\":\"2.0\",\"id\":85,\"method\":\"tools/call\",\"params\":{"
+             "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
+             "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,"
+             "\"cursor\":\"%s\"}}}",
+             tampered);
+    resp = cbm_mcp_server_handle(srv, req2);
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    free(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "invalid_cursor"));
+    free(inner);
+
+    /* Stale: an index run (upsert_project bumps the generation) invalidates
+     * outstanding cursors with a loud, actionable error. */
+    cbm_store_upsert_project(st, proj, "/tmp/page");
+    snprintf(req2, sizeof(req2),
+             "{\"jsonrpc\":\"2.0\",\"id\":82,\"method\":\"tools/call\",\"params\":{"
+             "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
+             "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,"
+             "\"cursor\":\"%s\"}}}",
+             tok1);
+    resp = cbm_mcp_server_handle(srv, req2);
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    free(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "stale_cursor"));
+    free(inner);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_trace_paging_filters_before_window_and_hashes_effective_args) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "trace-visible-page";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/trace-visible-page"), CBM_STORE_OK);
+
+    cbm_node_t hub = {.project = project,
+                      .label = "Function",
+                      .name = "hub",
+                      .qualified_name = "trace-visible-page.hub",
+                      .file_path = "src/hub.c",
+                      .start_line = 1,
+                      .end_line = 3};
+    cbm_node_t hidden = {.project = project,
+                         .label = "Function",
+                         .name = "hidden_test",
+                         .qualified_name = "trace-visible-page.hidden_test",
+                         .file_path = "tests/hidden_test.c",
+                         .start_line = 1,
+                         .end_line = 3};
+    cbm_node_t callee = {.project = project,
+                         .label = "Function",
+                         .name = "visible_callee",
+                         .qualified_name = "trace-visible-page.visible_callee",
+                         .file_path = "src/callee.c",
+                         .start_line = 1,
+                         .end_line = 3};
+    cbm_node_t caller = {.project = project,
+                         .label = "Function",
+                         .name = "visible_caller",
+                         .qualified_name = "trace-visible-page.visible_caller",
+                         .file_path = "src/caller.c",
+                         .start_line = 1,
+                         .end_line = 3};
+    int64_t hub_id = cbm_store_upsert_node(store, &hub);
+    int64_t hidden_id = cbm_store_upsert_node(store, &hidden); /* lower id: would consume page */
+    int64_t callee_id = cbm_store_upsert_node(store, &callee);
+    int64_t caller_id = cbm_store_upsert_node(store, &caller);
+    ASSERT_GT(hub_id, 0);
+    ASSERT_GT(hidden_id, 0);
+    ASSERT_GT(callee_id, 0);
+    ASSERT_GT(caller_id, 0);
+    cbm_edge_t edges[] = {
+        {.project = project, .source_id = hub_id, .target_id = hidden_id, .type = "CALLS"},
+        {.project = project, .source_id = hub_id, .target_id = callee_id, .type = "CALLS"},
+        {.project = project, .source_id = caller_id, .target_id = hub_id, .type = "CALLS"},
+    };
+    for (size_t i = 0; i < sizeof(edges) / sizeof(edges[0]); i++) {
+        ASSERT_GT(cbm_store_insert_edge(store, &edges[i]), 0);
+    }
+
+    const char *first_args = "{\"project\":\"trace-visible-page\",\"function_name\":\"hub\","
+                             "\"direction\":\"both\",\"depth\":1000,\"limit\":1,"
+                             "\"edge_types\":[\"CALLS\"],\"format\":\"json\"}";
+    char *response = cbm_mcp_handle_tool(srv, "trace_path", first_args);
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "visible_callee"));
+    ASSERT_NULL(strstr(inner, "hidden_test"));
+    ASSERT_NULL(strstr(inner, "visible_caller"));
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *next_value = yyjson_obj_get(yyjson_doc_get_root(doc), "next_cursor");
+    ASSERT_NOT_NULL(next_value);
+    char *next = strdup(yyjson_get_str(next_value));
+    ASSERT_NOT_NULL(next);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* A cursor is bound to edge_types; changing the traversed graph fails
+     * loudly instead of applying the watermark to unrelated rows. */
+    char args[768];
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"function_name\":\"hub\",\"direction\":\"both\","
+             "\"depth\":1000,\"limit\":1,\"edge_types\":[\"IMPORTS\"],"
+             "\"format\":\"json\",\"cursor\":\"%s\"}",
+             project, next);
+    response = cbm_mcp_handle_tool(srv, "trace_path", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "cursor_params_mismatch"));
+    free(inner);
+    free(response);
+
+    /* Replaying the same out-of-range depth works because cursor identity is
+     * based on the clamped effective value. This exact outbound boundary has
+     * zero inbound rows on page one, so it also binds the last-emitted-row
+     * watermark (no visited[-1]). */
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"function_name\":\"hub\",\"direction\":\"both\","
+             "\"depth\":1000,\"limit\":1,\"edge_types\":[\"CALLS\"],"
+             "\"format\":\"json\",\"cursor\":\"%s\"}",
+             project, next);
+    response = cbm_mcp_handle_tool(srv, "trace_path", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "visible_caller"));
+    ASSERT_NULL(strstr(inner, "visible_callee"));
+    ASSERT_NULL(strstr(inner, "next_cursor"));
+    free(inner);
+    free(response);
+    free(next);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_trace_budget_never_slices_identifiers) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "trace-byte-budget";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/trace-byte-budget"), CBM_STORE_OK);
+
+    cbm_node_t hub = {.project = project,
+                      .label = "Function",
+                      .name = "hub",
+                      .qualified_name = "trace-byte-budget.hub",
+                      .file_path = "src/hub.c",
+                      .start_line = 1,
+                      .end_line = 3};
+    int64_t hub_id = cbm_store_upsert_node(store, &hub);
+    ASSERT_GT(hub_id, 0);
+
+    enum { PREFIX_LEN = 7000 };
+    char *long_qn = malloc(PREFIX_LEN + sizeof(".leaf"));
+    ASSERT_NOT_NULL(long_qn);
+    memset(long_qn, 'p', PREFIX_LEN);
+    memcpy(long_qn + PREFIX_LEN, ".leaf", sizeof(".leaf"));
+    cbm_node_t leaf = {.project = project,
+                       .label = "Function",
+                       .name = "leaf",
+                       .qualified_name = long_qn,
+                       .file_path = "src/leaf.c",
+                       .start_line = 4,
+                       .end_line = 6};
+    int64_t leaf_id = cbm_store_upsert_node(store, &leaf);
+    ASSERT_GT(leaf_id, 0);
+    cbm_edge_t long_edge = {
+        .project = project, .source_id = hub_id, .target_id = leaf_id, .type = "CALLS"};
+    ASSERT_GT(cbm_store_insert_edge(store, &long_edge), 0);
+
+    char *tree_response =
+        cbm_mcp_handle_tool(srv, "trace_path",
+                            "{\"project\":\"trace-byte-budget\",\"function_name\":\"hub\","
+                            "\"direction\":\"outbound\",\"max_output_tokens\":10000}");
+    char *tree = extract_text_content(tree_response);
+    ASSERT_NOT_NULL(tree);
+    /* One long row is smaller when emitted directly than behind a one-entry
+     * group. The complete identifier is still present and never byte-sliced. */
+    char *long_prefix = cbm_strndup(long_qn, PREFIX_LEN);
+    ASSERT_NOT_NULL(long_prefix);
+    ASSERT_NOT_NULL(strstr(tree, long_qn));
+    ASSERT_NOT_NULL(strstr(tree, "(cols: qn hop)"));
+    ASSERT_NULL(strstr(tree, "qn = group prefix"));
+
+    char *json_response = cbm_mcp_handle_tool(
+        srv, "trace_path",
+        "{\"project\":\"trace-byte-budget\",\"function_name\":\"hub\","
+        "\"direction\":\"outbound\",\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *json = extract_text_content(json_response);
+    ASSERT_NOT_NULL(json);
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *callees = yyjson_obj_get(yyjson_doc_get_root(doc), "callees");
+    yyjson_val *groups = callees ? yyjson_obj_get(callees, "groups") : NULL;
+    yyjson_val *group = groups ? yyjson_arr_get(groups, 0) : NULL;
+    yyjson_val *rows = group ? yyjson_obj_get(group, "rows") : NULL;
+    yyjson_val *row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    const char *prefix = group ? yyjson_get_str(yyjson_obj_get(group, "qn_prefix")) : NULL;
+    const char *name = row ? yyjson_get_str(yyjson_arr_get(row, 0)) : NULL;
+    ASSERT_NOT_NULL(prefix);
+    ASSERT_NOT_NULL(name);
+    char *reconstructed = malloc(strlen(prefix) + strlen(name) + 2U);
+    ASSERT_NOT_NULL(reconstructed);
+    snprintf(reconstructed, strlen(prefix) + strlen(name) + 2U, "%s.%s", prefix, name);
+    ASSERT_STR_EQ(reconstructed, long_qn);
+    free(reconstructed);
+    yyjson_doc_free(doc);
+
+    /* A zero-row hard floor still reports what exists and how to continue.
+     * It must never mint a cursor from a row that was not actually returned. */
+    const char *floor_formats[] = {"tree", "json"};
+    for (size_t i = 0; i < sizeof(floor_formats) / sizeof(floor_formats[0]); i++) {
+        char floor_args[256];
+        snprintf(floor_args, sizeof(floor_args),
+                 "{\"project\":\"trace-byte-budget\",\"function_name\":\"hub\","
+                 "\"direction\":\"outbound\",\"max_output_tokens\":128,\"format\":\"%s\"}",
+                 floor_formats[i]);
+        char *floor_response = cbm_mcp_handle_tool(srv, "trace_path", floor_args);
+        char *floor = extract_text_content(floor_response);
+        ASSERT_NOT_NULL(floor);
+        ASSERT_TRUE(strlen(floor) <= 512U);
+        ASSERT_NULL(strstr(floor, long_prefix));
+        if (strcmp(floor_formats[i], "json") == 0) {
+            yyjson_doc *floor_doc = yyjson_read(floor, strlen(floor), 0);
+            ASSERT_NOT_NULL(floor_doc);
+            yyjson_val *floor_root = yyjson_doc_get_root(floor_doc);
+            ASSERT_EQ(yyjson_get_int(yyjson_obj_get(floor_root, "callees_total")), 1);
+            ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(floor_root, "callees_total_relation")),
+                          "eq");
+            ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(floor_root, "has_more")));
+            ASSERT_TRUE(
+                yyjson_get_bool(yyjson_obj_get(floor_root, "continuation_requires_higher_budget")));
+            ASSERT_TRUE(
+                yyjson_get_bool(yyjson_obj_get(floor_root, "output_budget_floor_exceeded")));
+            ASSERT_NULL(yyjson_obj_get(floor_root, "next_cursor"));
+            yyjson_doc_free(floor_doc);
+        } else {
+            ASSERT_NOT_NULL(strstr(floor, "callees_total: 1"));
+            ASSERT_NOT_NULL(strstr(floor, "callees_total_relation: eq"));
+            ASSERT_NOT_NULL(strstr(floor, "has_more: true"));
+            ASSERT_NOT_NULL(strstr(floor, "continuation_requires_higher_budget: true"));
+            ASSERT_NOT_NULL(strstr(floor, "output_budget_floor_exceeded: true"));
+            ASSERT_NULL(strstr(floor, "next: "));
+        }
+        free(floor);
+        free(floor_response);
+    }
+    free(json);
+    free(json_response);
+    free(tree);
+    free(tree_response);
+    free(long_prefix);
+    free(long_qn);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* A cursor identifies graph position, not presentation budget. Page one can
+ * fit a short row, while page two's first identity needs a higher budget. The
+ * hard floor emits no fabricated cursor, but retrying the original watermark
+ * with more max_output_tokens must resume successfully instead of failing a
+ * cursor-params hash check or replaying page one. */
+TEST(tool_trace_cursor_survives_output_budget_increase) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "trace-budget-cursor";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/trace-budget-cursor"), CBM_STORE_OK);
+    cbm_node_t hub = {.project = project,
+                      .label = "Function",
+                      .name = "hub",
+                      .qualified_name = "trace-budget-cursor.hub",
+                      .file_path = "src/hub.c",
+                      .start_line = 1,
+                      .end_line = 2};
+    cbm_node_t short_node = {.project = project,
+                             .label = "Function",
+                             .name = "short_row",
+                             .qualified_name = "trace-budget-cursor.short_row",
+                             .file_path = "src/short.c",
+                             .start_line = 3,
+                             .end_line = 4};
+    int64_t hub_id = cbm_store_upsert_node(store, &hub);
+    int64_t short_id = cbm_store_upsert_node(store, &short_node);
+    ASSERT_GT(hub_id, 0);
+    ASSERT_GT(short_id, hub_id);
+    enum { LONG_PREFIX = 3000 };
+    char *long_qn = malloc(LONG_PREFIX + sizeof(".long_row"));
+    ASSERT_NOT_NULL(long_qn);
+    memset(long_qn, 'q', LONG_PREFIX);
+    memcpy(long_qn + LONG_PREFIX, ".long_row", sizeof(".long_row"));
+    cbm_node_t long_node = {.project = project,
+                            .label = "Function",
+                            .name = "long_row",
+                            .qualified_name = long_qn,
+                            .file_path = "src/long.c",
+                            .start_line = 5,
+                            .end_line = 6};
+    int64_t long_id = cbm_store_upsert_node(store, &long_node);
+    ASSERT_GT(long_id, short_id);
+    cbm_edge_t short_edge = {
+        .project = project, .source_id = hub_id, .target_id = short_id, .type = "CALLS"};
+    cbm_edge_t long_edge = {
+        .project = project, .source_id = hub_id, .target_id = long_id, .type = "CALLS"};
+    ASSERT_GT(cbm_store_insert_edge(store, &short_edge), 0);
+    ASSERT_GT(cbm_store_insert_edge(store, &long_edge), 0);
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "trace_path",
+                            "{\"project\":\"trace-budget-cursor\",\"function_name\":\"hub\","
+                            "\"direction\":\"outbound\",\"limit\":1,\"max_output_tokens\":256,"
+                            "\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "short_row"));
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *next_value = yyjson_obj_get(yyjson_doc_get_root(doc), "next_cursor");
+    ASSERT_NOT_NULL(next_value);
+    char *cursor = strdup(yyjson_get_str(next_value));
+    ASSERT_NOT_NULL(cursor);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    char args[768];
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"function_name\":\"hub\","
+             "\"direction\":\"outbound\",\"limit\":1,\"max_output_tokens\":128,"
+             "\"format\":\"json\",\"cursor\":\"%s\"}",
+             project, cursor);
+    response = cbm_mcp_handle_tool(srv, "trace_path", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NULL(strstr(inner, "cursor_params_mismatch"));
+    ASSERT_NULL(strstr(inner, long_qn));
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *floor = yyjson_doc_get_root(doc);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(floor, "continuation_requires_higher_budget")));
+    ASSERT_NULL(yyjson_obj_get(floor, "next_cursor"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    snprintf(args, sizeof(args),
+             "{\"project\":\"%s\",\"function_name\":\"hub\","
+             "\"direction\":\"outbound\",\"limit\":1,\"max_output_tokens\":2000,"
+             "\"format\":\"json\",\"cursor\":\"%s\"}",
+             project, cursor);
+    response = cbm_mcp_handle_tool(srv, "trace_path", args);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NULL(strstr(inner, "cursor_params_mismatch"));
+    ASSERT_NULL(strstr(inner, "short_row"));
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *callees = yyjson_obj_get(yyjson_doc_get_root(doc), "callees");
+    ASSERT_NOT_NULL(callees);
+    const char *long_prefix_out = NULL;
+    yyjson_val *long_row = trace_grouped_row_named(callees, "long_row", &long_prefix_out);
+    ASSERT_NOT_NULL(long_row);
+    ASSERT_NOT_NULL(long_prefix_out);
+    size_t reconstructed_cap = strlen(long_prefix_out) + sizeof(".long_row");
+    char *reconstructed = malloc(reconstructed_cap);
+    ASSERT_NOT_NULL(reconstructed);
+    snprintf(reconstructed, reconstructed_cap, "%s.long_row", long_prefix_out);
+    ASSERT_STR_EQ(reconstructed, long_qn);
+    free(reconstructed);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+    free(cursor);
+    free(long_qn);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_trace_budget_drops_huge_optional_args_before_graph_row) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "trace-args-budget";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/trace-args-budget"), CBM_STORE_OK);
+    cbm_node_t caller = {.project = project,
+                         .label = "Function",
+                         .name = "caller",
+                         .qualified_name = "trace-args-budget.caller",
+                         .file_path = "src/caller.c",
+                         .start_line = 1,
+                         .end_line = 3};
+    cbm_node_t callee = {.project = project,
+                         .label = "Function",
+                         .name = "callee",
+                         .qualified_name = "trace-args-budget.callee",
+                         .file_path = "src/callee.c",
+                         .start_line = 4,
+                         .end_line = 6};
+    int64_t caller_id = cbm_store_upsert_node(store, &caller);
+    int64_t callee_id = cbm_store_upsert_node(store, &callee);
+    ASSERT_GT(caller_id, 0);
+    ASSERT_GT(callee_id, 0);
+    enum { ARG_BYTES = 40000 };
+    char *properties = malloc(ARG_BYTES + 32U);
+    ASSERT_NOT_NULL(properties);
+    memcpy(properties, "{\"args\":[\"", 10U);
+    memset(properties + 10U, 'x', ARG_BYTES);
+    memcpy(properties + 10U + ARG_BYTES, "\"]}", 4U);
+    properties[14U + ARG_BYTES] = '\0';
+    cbm_edge_t edge = {.project = project,
+                       .source_id = caller_id,
+                       .target_id = callee_id,
+                       .type = "CALLS",
+                       .properties_json = properties};
+    ASSERT_GT(cbm_store_insert_edge(store, &edge), 0);
+    for (int i = 0; i < 20; i++) {
+        char name[32];
+        char qualified_name[96];
+        snprintf(name, sizeof(name), "extra_%d", i);
+        snprintf(qualified_name, sizeof(qualified_name), "trace-args-budget.%s", name);
+        cbm_node_t extra = {.project = project,
+                            .label = "Function",
+                            .name = name,
+                            .qualified_name = qualified_name,
+                            .file_path = "src/extra.c",
+                            .start_line = 10 + i,
+                            .end_line = 11 + i};
+        int64_t extra_id = cbm_store_upsert_node(store, &extra);
+        ASSERT_GT(extra_id, 0);
+        cbm_edge_t extra_edge = {
+            .project = project, .source_id = caller_id, .target_id = extra_id, .type = "CALLS"};
+        ASSERT_GT(cbm_store_insert_edge(store, &extra_edge), 0);
+    }
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "trace_path",
+                            "{\"project\":\"trace-args-budget\",\"function_name\":\"caller\","
+                            "\"direction\":\"outbound\",\"mode\":\"data_flow\","
+                            "\"risk_labels\":true,\"include_evidence\":true,"
+                            "\"max_output_tokens\":256,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_TRUE(strlen(inner) <= 1024U);
+    ASSERT_NOT_NULL(strstr(inner, "trace-args-budget"));
+    ASSERT_NOT_NULL(strstr(inner, "optional_fields_omitted"));
+    ASSERT_NULL(strstr(inner, "xxxxxxxxxxxxxxxx"));
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *callees = yyjson_obj_get(root, "callees");
+    ASSERT_NOT_NULL(callees);
+    ASSERT_NOT_NULL(trace_grouped_row_named(callees, "callee", NULL));
+    yyjson_val *has_more = yyjson_obj_get(root, "has_more");
+    ASSERT_NOT_NULL(has_more);
+    yyjson_val *next_cursor = yyjson_obj_get(root, "next_cursor");
+    if (yyjson_get_bool(has_more)) {
+        ASSERT_NOT_NULL(next_cursor);
+    } else {
+        ASSERT_NULL(next_cursor);
+    }
+    yyjson_val *omitted = yyjson_obj_get(root, "omitted_optional_fields");
+    ASSERT_NOT_NULL(omitted);
+    ASSERT_EQ(yyjson_arr_size(omitted), 4);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(omitted, 0)), "risk");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(omitted, 1)), "args");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(omitted, 2)), "strategy");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(omitted, 3)), "confidence");
+    yyjson_doc_free(doc);
+
+    free(inner);
+    free(response);
+    free(properties);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_trace_reports_engine_saturation_as_lower_bound) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "trace-engine-cap";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/trace-engine-cap"), CBM_STORE_OK);
+    cbm_node_t hub = {.project = project,
+                      .label = "Function",
+                      .name = "hub",
+                      .qualified_name = "trace-engine-cap.hub",
+                      .file_path = "src/hub.c",
+                      .start_line = 1,
+                      .end_line = 3};
+    int64_t hub_id = cbm_store_upsert_node(store, &hub);
+    ASSERT_GT(hub_id, 0);
+    ASSERT_EQ(cbm_store_begin_bulk(store), CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_begin(store), CBM_STORE_OK);
+    for (int i = 0; i < 5001; i++) {
+        char name[32];
+        char qualified_name[64];
+        snprintf(name, sizeof(name), "callee_%04d", i);
+        snprintf(qualified_name, sizeof(qualified_name), "trace-engine-cap.%s", name);
+        char *oversized_qn = NULL;
+        const char *node_qn = qualified_name;
+        if (i == 0) {
+            oversized_qn = malloc(7000U + sizeof(".callee_0000"));
+            ASSERT_NOT_NULL(oversized_qn);
+            memset(oversized_qn, 'q', 7000U);
+            memcpy(oversized_qn + 7000U, ".callee_0000", sizeof(".callee_0000"));
+            node_qn = oversized_qn;
+        }
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = name,
+                           .qualified_name = node_qn,
+                           .file_path = "src/callees.c",
+                           .start_line = i + 1,
+                           .end_line = i + 2};
+        int64_t node_id = cbm_store_upsert_node(store, &node);
+        free(oversized_qn);
+        ASSERT_GT(node_id, 0);
+        cbm_edge_t edge = {
+            .project = project, .source_id = hub_id, .target_id = node_id, .type = "CALLS"};
+        ASSERT_GT(cbm_store_insert_edge(store, &edge), 0);
+    }
+    ASSERT_EQ(cbm_store_commit(store), CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_end_bulk(store), CBM_STORE_OK);
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "trace_path",
+                            "{\"project\":\"trace-engine-cap\",\"function_name\":\"hub\","
+                            "\"direction\":\"outbound\",\"depth\":1,\"limit\":5000,"
+                            "\"max_output_tokens\":100000,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "callees_total")), 5000);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "callees_total_relation")), "gte");
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "engine_saturated")));
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "truncated")));
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "truncation_reason")), "engine_limit");
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    ASSERT_NULL(yyjson_obj_get(root, "next_cursor"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* The hard floor preserves the engine's lower-bound relation while
+     * withholding the oversized first identity and any self-loop cursor. */
+    response = cbm_mcp_handle_tool(srv, "trace_path",
+                                   "{\"project\":\"trace-engine-cap\",\"function_name\":\"hub\","
+                                   "\"direction\":\"outbound\",\"depth\":1,\"limit\":5000,"
+                                   "\"max_output_tokens\":128,\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_TRUE(strlen(inner) <= 512U);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "callees_total")), 5000);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "callees_total_relation")), "gte");
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "has_more")));
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "continuation_requires_higher_budget")));
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "output_budget_floor_exceeded")));
+    ASSERT_NULL(yyjson_obj_get(root, "next_cursor"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(store_bfs_edge_data_is_skippable_and_bounded) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "trace-edge-budget";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/trace-edge-budget"), CBM_STORE_OK);
+
+    cbm_node_t hub = {.project = project,
+                      .label = "Function",
+                      .name = "hub",
+                      .qualified_name = "trace-edge-budget.hub",
+                      .file_path = "src/hub.c",
+                      .start_line = 1,
+                      .end_line = 3};
+    int64_t hub_id = cbm_store_upsert_node(store, &hub);
+    ASSERT_GT(hub_id, 0);
+    for (int i = 0; i < 2; i++) {
+        char name[24];
+        char qualified_name[64];
+        snprintf(name, sizeof(name), "callee_%d", i);
+        snprintf(qualified_name, sizeof(qualified_name), "trace-edge-budget.%s", name);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = name,
+                           .qualified_name = qualified_name,
+                           .file_path = "src/callee.c",
+                           .start_line = i + 1,
+                           .end_line = i + 2};
+        int64_t node_id = cbm_store_upsert_node(store, &node);
+        ASSERT_GT(node_id, 0);
+        cbm_edge_t edge = {
+            .project = project, .source_id = hub_id, .target_id = node_id, .type = "CALLS"};
+        ASSERT_GT(cbm_store_insert_edge(store, &edge), 0);
+    }
+
+    const char *types[] = {"CALLS"};
+    cbm_traverse_result_t traversal = {0};
+    ASSERT_EQ(
+        cbm_store_bfs_with_edge_limit(store, hub_id, "outbound", types, 1, 1, 10, 0, &traversal),
+        CBM_STORE_OK);
+    ASSERT_EQ(traversal.visited_count, 2);
+    ASSERT_EQ(traversal.edge_count, 0);
+    ASSERT_FALSE(traversal.edges_truncated);
+    cbm_store_traverse_free(&traversal);
+
+    memset(&traversal, 0, sizeof(traversal));
+    ASSERT_EQ(
+        cbm_store_bfs_with_edge_limit(store, hub_id, "outbound", types, 1, 1, 10, 1, &traversal),
+        CBM_STORE_OK);
+    ASSERT_EQ(traversal.visited_count, 2);
+    ASSERT_EQ(traversal.edge_count, 1);
+    ASSERT_TRUE(traversal.edges_truncated);
+    ASSERT_FALSE(traversal.truncated);
+    cbm_store_traverse_free(&traversal);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Regression: when same-named nodes differ in rank, trace must pick the real
+ * definition (callable, larger body) — NOT nodes[0]. The Module is inserted
+ * first; if trace took nodes[0] the outbound trace would be empty. */
+TEST(tool_trace_call_path_prefers_definition) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "pref-proj";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/pref");
+    /* nodes[0]: the WRONG match (a Module, tiny span), inserted first. */
+    cbm_node_t wrong = {.project = proj,
+                        .label = "Module",
+                        .name = "dup",
+                        .qualified_name = "pref-proj.dup",
+                        .file_path = "dup.x",
+                        .start_line = 1,
+                        .end_line = 1};
+    /* the real definition: a Function with a body. */
+    cbm_node_t def = {.project = proj,
+                      .label = "Function",
+                      .name = "dup",
+                      .qualified_name = "pref-proj.src.dup",
+                      .file_path = "src/dup.c",
+                      .start_line = 10,
+                      .end_line = 50};
+    cbm_node_t callee = {.project = proj,
+                         .label = "Function",
+                         .name = "callee",
+                         .qualified_name = "pref-proj.src.callee",
+                         .file_path = "src/dup.c",
+                         .start_line = 60,
+                         .end_line = 70};
+    ASSERT_GT(cbm_store_upsert_node(st, &wrong), 0);
+    int64_t id_def = cbm_store_upsert_node(st, &def);
+    int64_t id_callee = cbm_store_upsert_node(st, &callee);
+    ASSERT_GT(id_def, 0);
+    ASSERT_GT(id_callee, 0);
+    cbm_edge_t e = {.project = proj, .source_id = id_def, .target_id = id_callee, .type = "CALLS"};
+    cbm_store_insert_edge(st, &e);
+
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":62,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"trace_call_path\",\"arguments\":{\"function_name\":\"dup\","
+             "\"project\":\"pref-proj\",\"direction\":\"outbound\"}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NULL(strstr(inner, "ambiguous"));
+    /* picked the Function definition -> its outbound CALLS edge to "callee" shows */
+    ASSERT_NOT_NULL(strstr(inner, "callee"));
+    free(inner);
+    free(resp);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* CONTRACT PIN for the closed strategy vocabulary published by
+ * trace_path(include_evidence:true).
+ *
+ * The indexer records ~20 internal strategy names on CALLS edges and the set
+ * grows with every language added. We publish a CLASS, not the raw name, so a
+ * resolver rename cannot silently change a user-visible field. This test is
+ * what keeps that promise honest: every strategy production can emit must land
+ * in a known class. Adding lsp_foo_dispatch passes automatically; introducing a
+ * genuinely new KIND of resolution fails HERE and forces a deliberate decision
+ * about the public contract instead of leaking an internal name. */
+TEST(trace_evidence_strategy_class_vocabulary_is_closed) {
+    /* Every strategy string assigned anywhere in src/ + internal/ as of this
+     * commit, plus the two literals pass_calls.c writes directly. */
+    static const char *const lsp[] = {
+        "lsp_direct",         "lsp_base_dispatch",      "lsp_embed_dispatch",
+        "lsp_implicit_this",  "lsp_inherited_dispatch", "lsp_method_dispatch",
+        "lsp_proc_macro",     "lsp_smart_ptr_dispatch", "lsp_strategy_cross_file",
+        "lsp_trait_dispatch", "lsp_type_dispatch",      "lsp_virtual_dispatch"};
+    for (size_t i = 0; i < sizeof(lsp) / sizeof(lsp[0]); i++) {
+        const char *cls = cbm_mcp_edge_strategy_class(lsp[i]);
+        ASSERT_NOT_NULL(cls);
+        ASSERT_STR_EQ(cls, "lsp");
+    }
+    static const char *const lang[] = {"php_self_static", "php_static_resolved",
+                                       "perl_method_static", "perl_method_typed"};
+    for (size_t i = 0; i < sizeof(lang) / sizeof(lang[0]); i++) {
+        const char *cls = cbm_mcp_edge_strategy_class(lang[i]);
+        ASSERT_NOT_NULL(cls);
+        ASSERT_STR_EQ(cls, "language_rule");
+    }
+    static const char *const heur[] = {"callee_suffix", "field_type_hint", "service_pattern",
+                                       "fastapi_depends"};
+    for (size_t i = 0; i < sizeof(heur) / sizeof(heur[0]); i++) {
+        const char *cls = cbm_mcp_edge_strategy_class(heur[i]);
+        ASSERT_NOT_NULL(cls);
+        ASSERT_STR_EQ(cls, "heuristic");
+    }
+    /* A failed LSP resolution is reported as unresolved, not as "lsp" — the
+     * caller's question is whether the edge is trustworthy, and "we tried LSP
+     * and it did not resolve" answers no. */
+    ASSERT_STR_EQ(cbm_mcp_edge_strategy_class("lsp_unresolved"), "unresolved");
+    ASSERT_STR_EQ(cbm_mcp_edge_strategy_class("unknown"), "unresolved");
+    /* Only a NULL/empty strategy is unclassified — an unmapped non-empty value
+     * must never silently disappear from the output. */
+    ASSERT_NULL(cbm_mcp_edge_strategy_class(NULL));
+    ASSERT_NULL(cbm_mcp_edge_strategy_class(""));
+    ASSERT_STR_EQ(cbm_mcp_edge_strategy_class("some_future_resolver"), "heuristic");
+    PASS();
+}
+
+/* Distilled from #559 (@vvenegasv). The indexer already records
+ * {strategy, confidence} on every CALLS edge (pass_calls.c:355) and the store
+ * reads it back, but no tool ever surfaced it — an agent could see THAT A->B
+ * exists, never HOW it was resolved.
+ *
+ * Binds two things at once: the evidence columns appear only when asked for
+ * (default stays lean), and the published value is the CLASS, not the raw
+ * internal strategy name. Fails without the production change in both
+ * directions — no columns at all before, and "lsp_trait_dispatch" would leak
+ * verbatim if the classifier were bypassed. */
+TEST(tool_trace_path_evidence_is_opt_in_and_class_mapped) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "ev-proj";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/ev");
+    cbm_node_t caller = {.project = proj,
+                         .label = "Function",
+                         .name = "caller",
+                         .qualified_name = "ev-proj.src.caller",
+                         .file_path = "src/a.c",
+                         .start_line = 1,
+                         .end_line = 5};
+    cbm_node_t callee = {.project = proj,
+                         .label = "Function",
+                         .name = "target",
+                         .qualified_name = "ev-proj.src.target",
+                         .file_path = "src/a.c",
+                         .start_line = 10,
+                         .end_line = 20};
+    int64_t id_caller = cbm_store_upsert_node(st, &caller);
+    int64_t id_callee = cbm_store_upsert_node(st, &callee);
+    ASSERT_GT(id_caller, 0);
+    ASSERT_GT(id_callee, 0);
+    /* Exactly the shape pass_calls.c:355 writes in production. */
+    cbm_edge_t e = {.project = proj,
+                    .source_id = id_caller,
+                    .target_id = id_callee,
+                    .type = "CALLS",
+                    .properties_json = "{\"callee\":\"target\",\"confidence\":0.95,"
+                                       "\"strategy\":\"lsp_trait_dispatch\",\"candidates\":1}"};
+    ASSERT_GT(cbm_store_insert_edge(st, &e), 0);
+
+    /* Default: lean. No evidence columns, no strategy anywhere. */
+    char *plain = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":91,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"trace_path\",\"arguments\":{\"function_name\":\"caller\","
+             "\"project\":\"ev-proj\",\"direction\":\"outbound\"}}}");
+    ASSERT_NOT_NULL(plain);
+    char *plain_txt = extract_text_content(plain);
+    ASSERT_NOT_NULL(plain_txt);
+    ASSERT_NOT_NULL(strstr(plain_txt, "target")); /* positive control: the hop IS there */
+    ASSERT_NULL(strstr(plain_txt, "lsp"));
+    ASSERT_NULL(strstr(plain_txt, "0.95"));
+    free(plain_txt);
+    free(plain);
+
+    /* Opted in: the class and the confidence appear, the raw name does not. */
+    char *ev = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":92,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"trace_path\",\"arguments\":{\"function_name\":\"caller\","
+             "\"project\":\"ev-proj\",\"direction\":\"outbound\",\"include_evidence\":true}}}");
+    ASSERT_NOT_NULL(ev);
+    char *ev_txt = extract_text_content(ev);
+    ASSERT_NOT_NULL(ev_txt);
+    ASSERT_NOT_NULL(strstr(ev_txt, "target"));
+    ASSERT_NOT_NULL(strstr(ev_txt, "lsp"));
+    ASSERT_NOT_NULL(strstr(ev_txt, "0.95"));
+    /* The internal resolver name must NOT reach the client. */
+    ASSERT_NULL(strstr(ev_txt, "lsp_trait_dispatch"));
+    free(ev_txt);
+    free(ev);
+
+    /* #1542: the same request with format:"json" returned cols ["name","hop"]
+     * — include_evidence was implemented on the tree path only, so the callers
+     * most likely to ask for structured output were the ones who silently got
+     * nothing. The two formats must promise the same fields. */
+    char *ev_json = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":93,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"trace_path\",\"arguments\":{\"function_name\":\"caller\","
+             "\"project\":\"ev-proj\",\"direction\":\"outbound\",\"include_evidence\":true,"
+             "\"format\":\"json\"}}}");
+    ASSERT_NOT_NULL(ev_json);
+    char *ev_json_txt = extract_text_content(ev_json);
+    ASSERT_NOT_NULL(ev_json_txt);
+    yyjson_doc *ev_doc = yyjson_read(ev_json_txt, strlen(ev_json_txt), 0);
+    ASSERT_NOT_NULL(ev_doc);
+    yyjson_val *ev_root = yyjson_doc_get_root(ev_doc);
+    yyjson_val *ev_callees = yyjson_obj_get(ev_root, "callees");
+    yyjson_val *ev_cols = ev_callees ? yyjson_obj_get(ev_callees, "cols") : NULL;
+    ASSERT_NOT_NULL(ev_cols);
+    ASSERT_EQ(yyjson_arr_size(ev_cols), 4);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(ev_cols, 0)), "name");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(ev_cols, 1)), "hop");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(ev_cols, 2)), "strategy");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(ev_cols, 3)), "confidence");
+    yyjson_val *ev_row = trace_grouped_row_named(ev_callees, "target", NULL);
+    ASSERT_NOT_NULL(ev_row);
+    ASSERT_EQ(yyjson_arr_size(ev_row), yyjson_arr_size(ev_cols));
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(ev_row, 0)), "target");
+    ASSERT_EQ(yyjson_get_int(yyjson_arr_get(ev_row, 1)), 1);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(ev_row, 2)), "lsp");
+    ASSERT_EQ((int)(yyjson_get_real(yyjson_arr_get(ev_row, 3)) * 100.0), 95);
+    ASSERT_NULL(strstr(ev_json_txt, "lsp_trait_dispatch"));
+    yyjson_doc_free(ev_doc);
+    free(ev_json_txt);
+    free(ev_json);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Edge-data lookup must follow the traversal direction and shortest-path hop.
+ * The induced edge set contains a same-hop cross edge whose source is the row
+ * node and sorts before its real inbound predecessor. An arbitrary incident-
+ * edge scan attaches the decoy args/evidence; canonical predecessor selection
+ * must attach the edge that actually reaches the root. */
+TEST(tool_trace_path_edge_details_use_canonical_predecessor) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "trace-predecessor";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/trace-predecessor"), CBM_STORE_OK);
+
+    cbm_node_t wrong_target = {.project = project,
+                               .label = "Function",
+                               .name = "wrong_target",
+                               .qualified_name = "trace-predecessor.wrong_target",
+                               .file_path = "src/wrong.c",
+                               .start_line = 1,
+                               .end_line = 2};
+    cbm_node_t caller = {.project = project,
+                         .label = "Function",
+                         .name = "caller",
+                         .qualified_name = "trace-predecessor.caller",
+                         .file_path = "src/caller.c",
+                         .start_line = 3,
+                         .end_line = 4};
+    cbm_node_t root = {.project = project,
+                       .label = "Function",
+                       .name = "root",
+                       .qualified_name = "trace-predecessor.root",
+                       .file_path = "src/root.c",
+                       .start_line = 5,
+                       .end_line = 6};
+    int64_t wrong_id = cbm_store_upsert_node(store, &wrong_target);
+    int64_t caller_id = cbm_store_upsert_node(store, &caller);
+    int64_t root_id = cbm_store_upsert_node(store, &root);
+    ASSERT_GT(wrong_id, 0);
+    ASSERT_GT(caller_id, wrong_id);
+    ASSERT_GT(root_id, caller_id);
+
+    cbm_edge_t edges[] = {
+        {.project = project,
+         .source_id = caller_id,
+         .target_id = wrong_id,
+         .type = "CALLS",
+         .properties_json = "{\"args\":[{\"e\":\"decoy\"}],\"strategy\":\"callee_suffix\","
+                            "\"confidence\":0.1}"},
+        {.project = project,
+         .source_id = wrong_id,
+         .target_id = root_id,
+         .type = "CALLS",
+         .properties_json = "{\"args\":[{\"e\":\"other\"}],\"strategy\":\"callee_suffix\","
+                            "\"confidence\":0.2}"},
+        {.project = project,
+         .source_id = caller_id,
+         .target_id = root_id,
+         .type = "CALLS",
+         .properties_json = "{\"args\":[{\"e\":\"correct\"}],"
+                            "\"strategy\":\"lsp_trait_dispatch\",\"confidence\":0.9}"},
+    };
+    for (size_t i = 0; i < sizeof(edges) / sizeof(edges[0]); i++) {
+        ASSERT_GT(cbm_store_insert_edge(store, &edges[i]), 0);
+    }
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "trace_path",
+                            "{\"project\":\"trace-predecessor\",\"function_name\":\"root\","
+                            "\"direction\":\"inbound\",\"mode\":\"data_flow\","
+                            "\"include_evidence\":true,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *callers = yyjson_obj_get(yyjson_doc_get_root(doc), "callers");
+    ASSERT_NOT_NULL(callers);
+    yyjson_val *row = trace_grouped_row_named(callers, "caller", NULL);
+    ASSERT_NOT_NULL(row);
+    ASSERT_EQ(yyjson_get_int(yyjson_arr_get(row, 1)), 1);
+    yyjson_val *args = yyjson_arr_get(row, 2);
+    ASSERT_TRUE(yyjson_is_arr(args));
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(yyjson_arr_get(args, 0), "e")), "correct");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(row, 3)), "lsp");
+    ASSERT_EQ((int)(yyjson_get_real(yyjson_arr_get(row, 4)) * 10.0), 9);
+    ASSERT_NULL(strstr(inner, "decoy"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Audit contract: every opt-in trace column is positional. In particular,
+ * data_flow args must stay under `args`, evidence must appear exactly once at
+ * the tail, and the flat tree renderer selected by either risk_labels or
+ * data_flow must not discard requested evidence. include_tests exercises the
+ * widest flat-table shape and keeps a dotless qualified name in the payload. */
+TEST(tool_trace_path_evidence_columns_align_across_optional_modes) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "ev-align";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/ev-align");
+    cbm_node_t caller = {.project = proj,
+                         .label = "Function",
+                         .name = "caller",
+                         .qualified_name = "ev-align.src.caller",
+                         .file_path = "src/caller.c",
+                         .start_line = 1,
+                         .end_line = 5};
+    cbm_node_t target = {.project = proj,
+                         .label = "Function",
+                         .name = "target",
+                         .qualified_name = "ev-align.src.target",
+                         .file_path = "src/target.c",
+                         .start_line = 10,
+                         .end_line = 20};
+    cbm_node_t dotless_test = {.project = proj,
+                               .label = "Function",
+                               .name = "dotless_target",
+                               .qualified_name = "dotless_target",
+                               .file_path = "tests/test_target.c",
+                               .start_line = 1,
+                               .end_line = 4};
+    int64_t caller_id = cbm_store_upsert_node(st, &caller);
+    int64_t target_id = cbm_store_upsert_node(st, &target);
+    int64_t dotless_id = cbm_store_upsert_node(st, &dotless_test);
+    ASSERT_GT(caller_id, 0);
+    ASSERT_GT(target_id, 0);
+    ASSERT_GT(dotless_id, 0);
+    cbm_edge_t target_edge = {.project = proj,
+                              .source_id = caller_id,
+                              .target_id = target_id,
+                              .type = "CALLS",
+                              .properties_json =
+                                  "{\"args\":[{\"i\":0,\"e\":\"payload\"}],\"confidence\":0.95,"
+                                  "\"strategy\":\"lsp_trait_dispatch\"}"};
+    cbm_edge_t dotless_edge = {.project = proj,
+                               .source_id = caller_id,
+                               .target_id = dotless_id,
+                               .type = "CALLS",
+                               .properties_json =
+                                   "{\"args\":[{\"i\":1,\"e\":\"fixture\"}],\"confidence\":0.5,"
+                                   "\"strategy\":\"callee_suffix\"}"};
+    ASSERT_GT(cbm_store_insert_edge(st, &target_edge), 0);
+    ASSERT_GT(cbm_store_insert_edge(st, &dotless_edge), 0);
+
+    char *response = cbm_mcp_handle_tool(
+        srv, "trace_path",
+        "{\"project\":\"ev-align\",\"function_name\":\"caller\",\"direction\":\"outbound\","
+        "\"mode\":\"data_flow\",\"risk_labels\":true,\"include_tests\":true,"
+        "\"include_evidence\":true,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *callees = yyjson_obj_get(root, "callees");
+    ASSERT_NOT_NULL(callees);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(callees, "qn_rule")),
+                  "qn = qn_prefix == \"\" ? name : qn_prefix + \".\" + name");
+    yyjson_val *cols = yyjson_obj_get(callees, "cols");
+    ASSERT_NOT_NULL(cols);
+    static const char *const expected_cols[] = {"name", "hop",      "risk",      "test",
+                                                "args", "strategy", "confidence"};
+    ASSERT_EQ(yyjson_arr_size(cols), sizeof(expected_cols) / sizeof(expected_cols[0]));
+    for (size_t i = 0; i < sizeof(expected_cols) / sizeof(expected_cols[0]); i++) {
+        ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(cols, i)), expected_cols[i]);
+    }
+    yyjson_val *target_row = trace_grouped_row_named(callees, "target", NULL);
+    ASSERT_NOT_NULL(target_row);
+    ASSERT_EQ(yyjson_arr_size(target_row), yyjson_arr_size(cols));
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(target_row, 0)), "target");
+    ASSERT_EQ(yyjson_get_int(yyjson_arr_get(target_row, 1)), 1);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(target_row, 2)), "CRITICAL");
+    ASSERT_FALSE(yyjson_get_bool(yyjson_arr_get(target_row, 3)));
+    yyjson_val *target_args = yyjson_arr_get(target_row, 4);
+    ASSERT_TRUE(yyjson_is_arr(target_args));
+    ASSERT_EQ(yyjson_arr_size(target_args), 1);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(yyjson_arr_get(target_args, 0), "e")), "payload");
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(target_row, 5)), "lsp");
+    ASSERT_EQ((int)(yyjson_get_real(yyjson_arr_get(target_row, 6)) * 100.0), 95);
+
+    const char *dotless_prefix = NULL;
+    yyjson_val *dotless_row = trace_grouped_row_named(callees, "dotless_target", &dotless_prefix);
+    ASSERT_NOT_NULL(dotless_row);
+    ASSERT_NOT_NULL(dotless_prefix);
+    ASSERT_STR_EQ(dotless_prefix, "");
+    ASSERT_EQ(yyjson_arr_size(dotless_row), yyjson_arr_size(cols));
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(dotless_row, 0)), "dotless_target");
+    ASSERT_TRUE(yyjson_get_bool(yyjson_arr_get(dotless_row, 3)));
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(dotless_row, 5)), "heuristic");
+    ASSERT_EQ((int)(yyjson_get_real(yyjson_arr_get(dotless_row, 6)) * 10.0), 5);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* risk_labels alone selects the flat tree path without implicitly enabling
+     * evidence; the default stays lean even though the risk column is present. */
+    response = cbm_mcp_handle_tool(
+        srv, "trace_path",
+        "{\"project\":\"ev-align\",\"function_name\":\"caller\",\"direction\":\"outbound\","
+        "\"risk_labels\":true,\"include_tests\":true}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "(cols: qn hop risk test)"));
+    ASSERT_NOT_NULL(strstr(inner, "ev-align.src.target 1 CRITICAL false"));
+    ASSERT_NULL(strstr(inner, "strategy"));
+    ASSERT_NULL(strstr(inner, "0.95"));
+    free(inner);
+    free(response);
+
+    /* Combining risk_labels with evidence keeps evidence after risk/test. */
+    response = cbm_mcp_handle_tool(
+        srv, "trace_path",
+        "{\"project\":\"ev-align\",\"function_name\":\"caller\",\"direction\":\"outbound\","
+        "\"risk_labels\":true,\"include_tests\":true,\"include_evidence\":true}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "(cols: qn hop risk test strategy confidence)"));
+    ASSERT_NOT_NULL(strstr(inner, "ev-align.src.target 1 CRITICAL false lsp 0.95"));
+    ASSERT_NOT_NULL(strstr(inner, "dotless_target 1 CRITICAL true heuristic 0.5"));
+    free(inner);
+    free(response);
+
+    /* data_flow alone reaches the same flat renderer; args retain their
+     * established position and evidence follows them. */
+    response = cbm_mcp_handle_tool(
+        srv, "trace_path",
+        "{\"project\":\"ev-align\",\"function_name\":\"caller\",\"direction\":\"outbound\","
+        "\"mode\":\"data_flow\",\"include_tests\":true,\"include_evidence\":true}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "(cols: qn hop test args strategy confidence)"));
+    ASSERT_NOT_NULL(strstr(inner, "lsp 0.95"));
+    ASSERT_NOT_NULL(strstr(inner, "heuristic 0.5"));
+    free(inner);
+    free(response);
+
+    /* With only two unrelated prefixes, the direct table is smaller than two
+     * one-row groups. It keeps full QNs and the promised test marker. */
+    response = cbm_mcp_handle_tool(
+        srv, "trace_path",
+        "{\"project\":\"ev-align\",\"function_name\":\"caller\",\"direction\":\"outbound\","
+        "\"include_tests\":true,\"include_evidence\":true}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "(cols: qn hop test strategy confidence)"));
+    ASSERT_NOT_NULL(strstr(inner, "ev-align.src.target 1 false lsp 0.95"));
+    ASSERT_NOT_NULL(strstr(inner, "dotless_target 1 true heuristic 0.5"));
+    ASSERT_NULL(strstr(inner, "qn = group prefix"));
+    free(inner);
+    free(response);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Reproduce-first (#887): the client-supplied `depth` on trace_call_path must be
+ * clamped to the MCP ceiling (cbm_mcp_max_depth(), default 15). On origin/main
+ * an MCP_MAX_DEPTH=15 constant was defined but never applied — `depth` flowed
+ * straight into bfs_union_same_name, so an unbounded value drives the shared
+ * cbm_store_bfs to arbitrary depth. Over an 18-node call chain, depth=1000
+ * reaches n16/n17 (RED); with the clamp the walk stops at hop 15, so n15 is
+ * reached but n16 is not (GREEN). Quoted tokens ("n15"/"n16") match only the
+ * node-name field, never the qualified_name (preceded by '.'), so the boundary
+ * check is exact. */
+TEST(tool_trace_call_path_depth_clamped) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "depth-proj";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/depth");
+
+    /* Linear call chain n00 -CALLS-> n01 -> ... -> n17 (18 nodes). */
+    int64_t ids[18];
+    for (int i = 0; i < 18; i++) {
+        char name[8];
+        char qn[32];
+        snprintf(name, sizeof(name), "n%02d", i);
+        snprintf(qn, sizeof(qn), "depth-proj.n%02d", i);
+        cbm_node_t n = {.project = proj,
+                        .label = "Function",
+                        .name = name,
+                        .qualified_name = qn,
+                        .file_path = "chain.c",
+                        .start_line = 1,
+                        .end_line = 2};
+        ids[i] = cbm_store_upsert_node(st, &n);
+    }
+    for (int i = 0; i < 17; i++) {
+        cbm_edge_t e = {
+            .project = proj, .source_id = ids[i], .target_id = ids[i + 1], .type = "CALLS"};
+        cbm_store_insert_edge(st, &e);
+    }
+
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":71,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"trace_call_path\",\"arguments\":{\"function_name\":\"n00\","
+             "\"project\":\"depth-proj\",\"direction\":\"outbound\",\"depth\":1000}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+
+    /* Reached within the ceiling (proves the traversal ran) but clamped at 15.
+     * TOON rows carry bare QNs, so match the names unquoted. */
+    ASSERT_NOT_NULL(strstr(inner, "n15"));
+    ASSERT_NULL(strstr(inner, "n16"));
+
+    free(inner);
+    free(resp);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Reproduce-first (#650, distilled): two GENUINELY-DIFFERENT same-named functions
+ * whose bodies differ in length score differently, so the old exact-tie check did
+ * not flag them ambiguous — and bfs_union_same_name (#546) then merged the caller
+ * sets of both into one confidently-conflated answer (the mirror of #546's under-
+ * report). The fix: 2+ real callable defs => ambiguous (disambiguate), never union
+ * distinct symbols. RED before the pick_resolved_node real_def_count rule (response
+ * merged callerA+callerB), GREEN after (response is ambiguous, no "callers"). */
+TEST(tool_trace_call_path_distinct_defs_not_over_unioned) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "ou-proj";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/ou");
+    /* two unrelated real definitions of "dupreal", DIFFERENT body spans */
+    cbm_node_t da = {.project = proj,
+                     .label = "Function",
+                     .name = "dupreal",
+                     .qualified_name = "ou-proj.a.dupreal",
+                     .file_path = "a.c",
+                     .start_line = 10,
+                     .end_line = 20}; /* span 10 */
+    cbm_node_t db = {.project = proj,
+                     .label = "Function",
+                     .name = "dupreal",
+                     .qualified_name = "ou-proj.b.dupreal",
+                     .file_path = "b.c",
+                     .start_line = 10,
+                     .end_line = 40}; /* span 30 (no tie) */
+    cbm_node_t ca = {.project = proj,
+                     .label = "Function",
+                     .name = "callerA",
+                     .qualified_name = "ou-proj.a.callerA",
+                     .file_path = "a.c",
+                     .start_line = 30,
+                     .end_line = 40};
+    cbm_node_t cb = {.project = proj,
+                     .label = "Function",
+                     .name = "callerB",
+                     .qualified_name = "ou-proj.b.callerB",
+                     .file_path = "b.c",
+                     .start_line = 50,
+                     .end_line = 60};
+    int64_t id_da = cbm_store_upsert_node(st, &da);
+    int64_t id_db = cbm_store_upsert_node(st, &db);
+    int64_t id_ca = cbm_store_upsert_node(st, &ca);
+    int64_t id_cb = cbm_store_upsert_node(st, &cb);
+    ASSERT_GT(id_da, 0);
+    ASSERT_GT(id_db, 0);
+    ASSERT_GT(id_ca, 0);
+    ASSERT_GT(id_cb, 0);
+    cbm_edge_t ea = {.project = proj, .source_id = id_ca, .target_id = id_da, .type = "CALLS"};
+    cbm_edge_t eb = {.project = proj, .source_id = id_cb, .target_id = id_db, .type = "CALLS"};
+    cbm_store_insert_edge(st, &ea);
+    cbm_store_insert_edge(st, &eb);
+
+    char *resp = cbm_mcp_server_handle(
+        srv,
+        "{\"jsonrpc\":\"2.0\",\"id\":63,\"method\":\"tools/call\","
+        "\"params\":{\"name\":\"trace_call_path\",\"arguments\":{\"function_name\":\"dupreal\","
+        "\"project\":\"ou-proj\",\"direction\":\"inbound\"}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    /* distinct symbols must be disambiguated, not merged into one caller set */
+    ASSERT_NOT_NULL(strstr(inner, "ambiguous"));
+    ASSERT_NOT_NULL(strstr(inner, "suggestions"));
+    ASSERT_NULL(strstr(inner, "\"callers\""));
     free(inner);
     free(resp);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Multi-seed union hop semantics: bfs_union_same_name deduped visited nodes
- * keep-FIRST-seen, so a node reached at hop 2 from the first seed kept hop 2
- * even when the second seed reaches it at hop 1. hop feeds risk_labels and
- * (soon) pagination watermarks — it must be the MINIMUM across seeds, matching
- * the single-BFS MIN(hop) semantics (#797). */
-TEST(tool_trace_union_records_min_hop_across_seeds) {
+/* Guard that the ambiguity gate does NOT regress the #546 fix: a real .ts
+ * implementation plus a body-less ambient .d.ts stub is ONE logical symbol
+ * (one real callable def + a fragment), so it must stay non-ambiguous and the
+ * caller sets from both nodes must be unioned. */
+TEST(tool_trace_call_path_dts_stub_unions_with_impl) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    cbm_store_t *st = cbm_mcp_server_store(srv);
+    const char *proj = "dts-proj";
+    cbm_mcp_server_set_project(srv, proj);
+    cbm_store_upsert_project(st, proj, "/tmp/dts");
+    cbm_node_t impl = {.project = proj,
+                       .label = "Function",
+                       .name = "sym546",
+                       .qualified_name = "dts-proj.impl.sym546",
+                       .file_path = "src/sym.ts",
+                       .start_line = 10,
+                       .end_line = 30}; /* real body */
+    cbm_node_t stub = {.project = proj,
+                       .label = "Function",
+                       .name = "sym546",
+                       .qualified_name = "dts-proj.stub.sym546",
+                       .file_path = "types/sym.d.ts",
+                       .start_line = 5,
+                       .end_line = 5}; /* body-less ambient decl */
+    cbm_node_t crel = {.project = proj,
+                       .label = "Function",
+                       .name = "callerRel",
+                       .qualified_name = "dts-proj.callerRel",
+                       .file_path = "src/rel.ts",
+                       .start_line = 1,
+                       .end_line = 8};
+    cbm_node_t cali = {.project = proj,
+                       .label = "Function",
+                       .name = "callerAlias",
+                       .qualified_name = "dts-proj.callerAlias",
+                       .file_path = "src/ali.ts",
+                       .start_line = 1,
+                       .end_line = 8};
+    int64_t id_impl = cbm_store_upsert_node(st, &impl);
+    int64_t id_stub = cbm_store_upsert_node(st, &stub);
+    int64_t id_crel = cbm_store_upsert_node(st, &crel);
+    int64_t id_cali = cbm_store_upsert_node(st, &cali);
+    ASSERT_GT(id_impl, 0);
+    ASSERT_GT(id_stub, 0);
+    ASSERT_GT(id_crel, 0);
+    ASSERT_GT(id_cali, 0);
+    /* callers split by import style: relative -> impl, path-alias -> stub */
+    cbm_edge_t er = {.project = proj, .source_id = id_crel, .target_id = id_impl, .type = "CALLS"};
+    cbm_edge_t el = {.project = proj, .source_id = id_cali, .target_id = id_stub, .type = "CALLS"};
+    cbm_store_insert_edge(st, &er);
+    cbm_store_insert_edge(st, &el);
+
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":64,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"trace_call_path\",\"arguments\":{\"function_name\":\"sym546\","
+             "\"project\":\"dts-proj\",\"direction\":\"inbound\"}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NULL(strstr(inner, "ambiguous"));
+    /* union across impl + stub: BOTH callers appear (this is the #546 fix) */
+    ASSERT_NOT_NULL(strstr(inner, "callerRel"));
+    ASSERT_NOT_NULL(strstr(inner, "callerAlias"));
+    free(inner);
+    free(resp);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_delete_project_not_found) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":22,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"delete_project\","
+                                   "\"arguments\":{\"project\":\"nonexistent\"}}}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "not_found"));
+    free(resp);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_delete_project_mutation_guard_blocks_then_releases) {
+    char cache[256];
+    snprintf(cache, sizeof(cache), "/tmp/cbm-mcp-delete-guard-XXXXXX");
+    if (!cbm_mkdtemp(cache)) {
+        PASS();
+    }
+
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    cbm_setenv("CBM_CACHE_DIR", cache, 1);
+
+    const char *project = "guard-delete-project";
+    char db_path[CBM_SZ_1K];
+    snprintf(db_path, sizeof(db_path), "%s/%s.db", cache, project);
+    cbm_store_t *setup = cbm_store_open_path(db_path);
+    ASSERT_NOT_NULL(setup);
+    ASSERT_EQ(cbm_store_upsert_project(setup, project, "/tmp/guard-delete-project"), CBM_STORE_OK);
+    cbm_store_close(setup);
+    ASSERT_TRUE(cbm_file_exists(db_path));
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    mcp_mutation_guard_probe_t probe = {.deny_begin_call = 1};
+    cbm_mcp_server_set_project_mutation_guard(srv, mcp_mutation_guard_probe_begin,
+                                              mcp_mutation_guard_probe_end, &probe);
+
+    char *resp =
+        cbm_mcp_handle_tool(srv, "delete_project", "{\"project\":\"guard-delete-project\"}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "blocked"));
+    ASSERT_EQ(probe.begin_count, 1);
+    ASSERT_EQ(probe.end_count, 0);
+    ASSERT_STR_EQ(probe.begin_projects[0], project);
+    ASSERT_TRUE(cbm_file_exists(db_path));
+    free(resp);
+
+    probe.deny_begin_call = 0;
+    resp = cbm_mcp_handle_tool(srv, "delete_project", "{\"project\":\"guard-delete-project\"}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "deleted"));
+    ASSERT_EQ(probe.begin_count, 2);
+    ASSERT_EQ(probe.end_count, 1);
+    ASSERT_STR_EQ(probe.begin_projects[1], project);
+    ASSERT_STR_EQ(probe.end_projects[0], project);
+    ASSERT_FALSE(cbm_file_exists(db_path));
+    free(resp);
+
+    cbm_mcp_server_free(srv);
+    cleanup_project_db(cache, project);
+    cbm_rmdir(cache);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    PASS();
+}
+
+TEST(tool_index_repository_mutation_guard_blocks_before_local_worker) {
+    char root[CBM_SZ_1K];
+    (void)snprintf(root, sizeof(root), "%s/cbm-index-guard-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(root));
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    mcp_mutation_guard_probe_t probe = {.deny_begin_call = 1};
+    cbm_mcp_server_set_project_mutation_guard(srv, mcp_mutation_guard_probe_begin,
+                                              mcp_mutation_guard_probe_end, &probe);
+
+    char args[CBM_SZ_2K];
+    (void)snprintf(args, sizeof(args),
+                   "{\"repo_path\":\"%s\",\"name\":\"GuardedIndex\","
+                   "\"mode\":\"fast\"}",
+                   root);
+    int spawn_before = cbm_index_supervisor_spawn_count();
+    char *response = cbm_mcp_handle_tool(srv, "index_repository", args);
+    int spawn_after = cbm_index_supervisor_spawn_count();
+
+    ASSERT_NOT_NULL(response);
+    ASSERT_NOT_NULL(strstr(response, "blocked"));
+    ASSERT_EQ(probe.begin_count, 1);
+    ASSERT_EQ(probe.end_count, 0);
+    ASSERT_STR_EQ(probe.begin_projects[0], "GuardedIndex");
+    ASSERT_EQ(spawn_after, spawn_before);
+
+    free(response);
+    cbm_mcp_server_free(srv);
+    (void)th_rmtree(root);
+    PASS();
+}
+
+TEST(tool_get_architecture_empty) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":24,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"get_architecture\","
+                                   "\"arguments\":{\"project\":\"nonexistent\"}}}");
+    ASSERT_NOT_NULL(resp);
+    /* No store for nonexistent project — should return project error */
+    ASSERT_TRUE(strstr(resp, "not found") || strstr(resp, "not indexed"));
+    free(resp);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+/* Regression for #281: handle_get_architecture must actually call
+ * cbm_store_get_architecture and surface its sections. Before the fix
+ * only label/edge histograms were emitted regardless of which aspects
+ * were requested. The store-side arch_entry_points query reads
+ * properties.is_entry_point on Function nodes, so we tag one node and
+ * assert the resulting JSON surfaces an "entry_points" array containing
+ * the tagged function — which is impossible without the wiring. */
+TEST(tool_get_architecture_emits_populated_sections) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
     cbm_store_t *st = cbm_mcp_server_store(srv);
-    const char *proj = "dualproj";
+    ASSERT_NOT_NULL(st);
+
+    const char *proj = "arch-test";
     cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/dual");
+    cbm_store_upsert_project(st, proj, "/tmp/arch-test");
 
-    /* One real definition + one body-less stub (start==end) — the #546/#650
-     * shape pick_resolved_node resolves WITHOUT ambiguity while
-     * bfs_union_same_name still traverses both. Seed A (real def, lower id,
-     * traversed first) reaches tgt only via mid (hop 2); the stub seed B
-     * reaches tgt directly (hop 1). */
-    cbm_node_t sa = {.project = proj,
-                     .label = "Function",
-                     .name = "dual",
-                     .qualified_name = "dualproj.a.dual",
-                     .file_path = "a.c",
-                     .start_line = 1,
-                     .end_line = 50};
-    cbm_node_t sb = {.project = proj,
-                     .label = "Function",
-                     .name = "dual",
-                     .qualified_name = "dualproj.b.dual",
-                     .file_path = "b.d.ts",
-                     .start_line = 1,
-                     .end_line = 1};
-    cbm_node_t mid = {.project = proj,
-                      .label = "Function",
-                      .name = "mid",
-                      .qualified_name = "dualproj.c.mid",
-                      .file_path = "c.c",
-                      .start_line = 1,
-                      .end_line = 5};
-    cbm_node_t tgt = {.project = proj,
-                      .label = "Function",
-                      .name = "tgt",
-                      .qualified_name = "dualproj.c.tgt",
-                      .file_path = "c.c",
-                      .start_line = 10,
-                      .end_line = 15};
-    int64_t ida = cbm_store_upsert_node(st, &sa);
-    int64_t idb = cbm_store_upsert_node(st, &sb);
-    int64_t idm = cbm_store_upsert_node(st, &mid);
-    int64_t idt = cbm_store_upsert_node(st, &tgt);
-    ASSERT_GT(ida, 0);
-    ASSERT_GT(idb, 0);
-    ASSERT_GT(idm, 0);
-    ASSERT_GT(idt, 0);
-    cbm_edge_t e1 = {.project = proj, .source_id = ida, .target_id = idm, .type = "CALLS"};
-    cbm_edge_t e2 = {.project = proj, .source_id = idm, .target_id = idt, .type = "CALLS"};
-    cbm_edge_t e3 = {.project = proj, .source_id = idb, .target_id = idt, .type = "CALLS"};
-    ASSERT_GT(cbm_store_insert_edge(st, &e1), 0);
-    ASSERT_GT(cbm_store_insert_edge(st, &e2), 0);
-    ASSERT_GT(cbm_store_insert_edge(st, &e3), 0);
+    cbm_node_t main_fn = {0};
+    main_fn.project = proj;
+    main_fn.label = "Function";
+    main_fn.name = "main";
+    main_fn.qualified_name = "arch-test.cmd.main";
+    main_fn.file_path = "cmd/main.go";
+    main_fn.start_line = 1;
+    main_fn.end_line = 3;
+    main_fn.properties_json = "{\"is_entry_point\":true}";
+    ASSERT_GT(cbm_store_upsert_node(st, &main_fn), 0);
 
     char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":62,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"trace_call_path\","
-             "\"arguments\":{\"function_name\":\"dual\",\"project\":\"dualproj\","
-             "\"direction\":\"outbound\",\"depth\":3}}}");
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":91,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"get_architecture\","
+             "\"arguments\":{\"project\":\"arch-test\",\"aspects\":[\"all\"]}}}");
     ASSERT_NOT_NULL(resp);
     char *inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
-    /* tgt is one hop from seed B — the union must record hop 1, not seed A's 2. */
-    ASSERT_NOT_NULL(strstr(inner, "  tgt 1"));
-    ASSERT_NULL(strstr(inner, "  tgt 2"));
+
+    /* The handler always emits node/edge counts and schema histograms;
+     * those existed before #281. The "entry_points" array only appears
+     * when cbm_store_get_architecture is actually called and its result
+     * is serialized — which is exactly what #281 wires up. */
+    ASSERT_NOT_NULL(strstr(inner, "entry_points:"));
+    ASSERT_NOT_NULL(strstr(inner, "main"));
+
     free(inner);
     free(resp);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Exactly-once trace pagination: 12 callees paged at limit=5 must yield
- * 5+5+2 rows with every callee appearing on exactly one page, exact totals
- * on every page, and a final page without a cursor. Stale and mismatched
- * cursors must fail with teaching errors, never silently restart. */
-TEST(tool_trace_pagination_exactly_once) {
+/* Distills PR #560 (overview subset): "overview" must expand to a compact
+ * subset — every aspect EXCEPT file_tree. Before the fix, "overview" was not
+ * registered in either aspect gate (want_aspect in store.c, aspect_wanted in
+ * mcp.c), so aspects=["overview"] silently degraded to just
+ * {total_nodes,total_edges}. RED on unfixed code: no "entry_points" key. */
+TEST(tool_get_architecture_overview_compact_subset_pr560) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
     cbm_store_t *st = cbm_mcp_server_store(srv);
-    const char *proj = "pageproj";
+    ASSERT_NOT_NULL(st);
+
+    const char *proj = "arch560";
     cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/page");
+    cbm_store_upsert_project(st, proj, "/tmp/arch560");
 
-    cbm_node_t hub = {.project = proj,
-                      .label = "Function",
-                      .name = "hub",
-                      .qualified_name = "pageproj.h.hub",
-                      .file_path = "h.c",
-                      .start_line = 1,
-                      .end_line = 9};
-    int64_t hid = cbm_store_upsert_node(st, &hub);
-    ASSERT_GT(hid, 0);
-    enum { CALLEES = 12 };
-    for (int i = 0; i < CALLEES; i++) {
-        char nm[16];
-        char qn[48];
-        snprintf(nm, sizeof(nm), "c%02d", i);
-        snprintf(qn, sizeof(qn), "pageproj.m.c%02d", i);
-        cbm_node_t n = {.project = proj,
-                        .label = "Function",
-                        .name = nm,
-                        .qualified_name = qn,
-                        .file_path = "m.c",
-                        .start_line = 1,
-                        .end_line = 3};
-        int64_t nid = cbm_store_upsert_node(st, &n);
-        ASSERT_GT(nid, 0);
-        cbm_edge_t e = {.project = proj, .source_id = hid, .target_id = nid, .type = "CALLS"};
-        ASSERT_GT(cbm_store_insert_edge(st, &e), 0);
-    }
+    cbm_node_t main_fn = {0};
+    main_fn.project = proj;
+    main_fn.label = "Function";
+    main_fn.name = "main";
+    main_fn.qualified_name = "arch560.cmd.main";
+    main_fn.file_path = "cmd/main.go";
+    main_fn.start_line = 1;
+    main_fn.end_line = 3;
+    main_fn.properties_json = "{\"is_entry_point\":true}";
+    ASSERT_GT(cbm_store_upsert_node(st, &main_fn), 0);
 
-    char pages[3][4096];
-    char tok[192] = "";
-    int npages = 0;
-    for (; npages < 3; npages++) {
-        char req[640];
-        if (tok[0]) {
-            snprintf(req, sizeof(req),
-                     "{\"jsonrpc\":\"2.0\",\"id\":80,\"method\":\"tools/call\",\"params\":{"
-                     "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
-                     "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,"
-                     "\"cursor\":\"%s\"}}}",
-                     tok);
-        } else {
-            snprintf(req, sizeof(req),
-                     "{\"jsonrpc\":\"2.0\",\"id\":80,\"method\":\"tools/call\",\"params\":{"
-                     "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
-                     "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5}}}");
-        }
-        char *resp = cbm_mcp_server_handle(srv, req);
-        ASSERT_NOT_NULL(resp);
-        char *inner = extract_text_content(resp);
-        free(resp);
-        ASSERT_NOT_NULL(inner);
-        snprintf(pages[npages], sizeof(pages[npages]), "%s", inner);
-        ASSERT_NOT_NULL(strstr(inner, "callees_total: 12")); /* exact total, every page */
-        const char *nx = strstr(inner, "next: ");
-        if (nx) {
-            const char *e = strchr(nx + 6, '\n');
-            size_t tl = e ? (size_t)(e - (nx + 6)) : strlen(nx + 6);
-            ASSERT_TRUE(tl < sizeof(tok));
-            memcpy(tok, nx + 6, tl);
-            tok[tl] = '\0';
-        } else {
-            tok[0] = '\0';
-        }
-        free(inner);
-        if (!tok[0]) {
-            npages++;
-            break;
-        }
-    }
-    ASSERT_EQ(npages, 3); /* 5 + 5 + 2 */
-    /* Exactly-once: every callee appears on exactly ONE page. */
-    for (int i = 0; i < CALLEES; i++) {
-        char qn[48];
-        snprintf(qn, sizeof(qn), "  c%02d 1\n", i);
-        int seen = 0;
-        for (int p = 0; p < 3; p++) {
-            if (strstr(pages[p], qn)) {
-                seen++;
-            }
-        }
-        ASSERT_EQ(seen, 1);
-    }
-    /* Final page carries no cursor. */
-    ASSERT_NULL(strstr(pages[2], "next: "));
+    /* A File node so the file_tree aspect has real content — makes the
+     * "overview drops file_tree" assertion below non-vacuous. */
+    cbm_node_t file_node = {.project = proj,
+                            .label = "File",
+                            .name = "main.go",
+                            .qualified_name = "arch560.cmd.main.go",
+                            .file_path = "cmd/main.go"};
+    ASSERT_GT(cbm_store_upsert_node(st, &file_node), 0);
 
-    /* Params mismatch: replay a page-2-era cursor with a different depth. */
-    const char *nx1 = strstr(pages[0], "next: ");
-    ASSERT_NOT_NULL(nx1);
-    char tok1[192];
-    const char *e1 = strchr(nx1 + 6, '\n');
-    size_t tl1 = e1 ? (size_t)(e1 - (nx1 + 6)) : strlen(nx1 + 6);
-    memcpy(tok1, nx1 + 6, tl1);
-    tok1[tl1] = '\0';
-    char req2[640];
-    snprintf(req2, sizeof(req2),
-             "{\"jsonrpc\":\"2.0\",\"id\":81,\"method\":\"tools/call\",\"params\":{"
-             "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
-             "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,\"depth\":2,"
-             "\"cursor\":\"%s\"}}}",
-             tok1);
-    char *resp = cbm_mcp_server_handle(srv, req2);
+    /* Sanity: with "all", both entry_points and file_tree surface. */
+    char *resp_all = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":560,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"get_architecture\","
+             "\"arguments\":{\"project\":\"arch560\",\"aspects\":[\"all\"]}}}");
+    ASSERT_NOT_NULL(resp_all);
+    char *inner_all = extract_text_content(resp_all);
+    ASSERT_NOT_NULL(inner_all);
+    ASSERT_NOT_NULL(strstr(inner_all, "entry_points:"));
+    ASSERT_NOT_NULL(strstr(inner_all, "file_tree:"));
+    free(inner_all);
+    free(resp_all);
+
+    /* "overview": substantive content (entry_points, node_labels) but NO
+     * file_tree section. */
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":561,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"get_architecture\","
+             "\"arguments\":{\"project\":\"arch560\",\"aspects\":[\"overview\"]}}}");
     ASSERT_NOT_NULL(resp);
     char *inner = extract_text_content(resp);
-    free(resp);
     ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "cursor_params_mismatch"));
-    free(inner);
+    ASSERT_NOT_NULL(strstr(inner, "entry_points:"));
+    ASSERT_NOT_NULL(strstr(inner, "node_labels:"));
+    ASSERT_NULL(strstr(inner, "file_tree:"));
 
-    /* Stale: an index run (upsert_project bumps the generation) invalidates
-     * outstanding cursors with a loud, actionable error. */
-    cbm_store_upsert_project(st, proj, "/tmp/page");
-    snprintf(req2, sizeof(req2),
-             "{\"jsonrpc\":\"2.0\",\"id\":82,\"method\":\"tools/call\",\"params\":{"
-             "\"name\":\"trace_call_path\",\"arguments\":{\"project\":\"pageproj\","
-             "\"function_name\":\"hub\",\"direction\":\"outbound\",\"limit\":5,"
-             "\"cursor\":\"%s\"}}}",
-             tok1);
-    resp = cbm_mcp_server_handle(srv, req2);
-    ASSERT_NOT_NULL(resp);
-    inner = extract_text_content(resp);
-    free(resp);
-    ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "stale_cursor"));
     free(inner);
-
+    free(resp);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Regression: when same-named nodes differ in rank, trace must pick the real
- * definition (callable, larger body) — NOT nodes[0]. The Module is inserted
- * first; if trace took nodes[0] the outbound trace would be empty. */
-TEST(tool_trace_call_path_prefers_definition) {
+/* Distills PR #560 (server-side validation): unknown aspect tokens must be
+ * rejected with an isError result listing the valid values. Before the fix
+ * the JSON-Schema accepted any string and both aspect gates simply never
+ * matched, so a typo like "bogus_aspect" produced a silent near-empty payload
+ * with isError:false. RED on unfixed code: no isError, no "Unknown aspect". */
+TEST(tool_get_architecture_rejects_unknown_aspect_pr560) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
     cbm_store_t *st = cbm_mcp_server_store(srv);
-    const char *proj = "pref-proj";
+    ASSERT_NOT_NULL(st);
+
+    const char *proj = "arch560v";
     cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/pref");
-    /* nodes[0]: the WRONG match (a Module, tiny span), inserted first. */
-    cbm_node_t wrong = {.project = proj,
-                        .label = "Module",
-                        .name = "dup",
-                        .qualified_name = "pref-proj.dup",
-                        .file_path = "dup.x",
-                        .start_line = 1,
-                        .end_line = 1};
-    /* the real definition: a Function with a body. */
-    cbm_node_t def = {.project = proj,
-                      .label = "Function",
-                      .name = "dup",
-                      .qualified_name = "pref-proj.src.dup",
-                      .file_path = "src/dup.c",
-                      .start_line = 10,
-                      .end_line = 50};
-    cbm_node_t callee = {.project = proj,
-                         .label = "Function",
-                         .name = "callee",
-                         .qualified_name = "pref-proj.src.callee",
-                         .file_path = "src/dup.c",
-                         .start_line = 60,
-                         .end_line = 70};
-    ASSERT_GT(cbm_store_upsert_node(st, &wrong), 0);
-    int64_t id_def = cbm_store_upsert_node(st, &def);
-    int64_t id_callee = cbm_store_upsert_node(st, &callee);
-    ASSERT_GT(id_def, 0);
-    ASSERT_GT(id_callee, 0);
-    cbm_edge_t e = {.project = proj, .source_id = id_def, .target_id = id_callee, .type = "CALLS"};
-    cbm_store_insert_edge(st, &e);
+    cbm_store_upsert_project(st, proj, "/tmp/arch560v");
 
     char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":62,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"trace_call_path\",\"arguments\":{\"function_name\":\"dup\","
-             "\"project\":\"pref-proj\",\"direction\":\"outbound\"}}}");
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":562,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"get_architecture\","
+             "\"arguments\":{\"project\":\"arch560v\",\"aspects\":[\"bogus_aspect\"]}}}");
     ASSERT_NOT_NULL(resp);
-    char *inner = extract_text_content(resp);
-    ASSERT_NOT_NULL(inner);
-    ASSERT_NULL(strstr(inner, "ambiguous"));
-    /* picked the Function definition -> its outbound CALLS edge to "callee" shows */
-    ASSERT_NOT_NULL(strstr(inner, "callee"));
-    free(inner);
+    ASSERT_NOT_NULL(strstr(resp, "\"isError\":true"));
+    ASSERT_NOT_NULL(strstr(resp, "Unknown aspect 'bogus_aspect'"));
+    /* The error must teach the valid vocabulary, including the new token. */
+    ASSERT_NOT_NULL(strstr(resp, "overview"));
+    ASSERT_NOT_NULL(strstr(resp, "file_tree"));
+
     free(resp);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* CONTRACT PIN for the closed strategy vocabulary published by
- * trace_path(include_evidence:true).
- *
- * The indexer records ~20 internal strategy names on CALLS edges and the set
- * grows with every language added. We publish a CLASS, not the raw name, so a
- * resolver rename cannot silently change a user-visible field. This test is
- * what keeps that promise honest: every strategy production can emit must land
- * in a known class. Adding lsp_foo_dispatch passes automatically; introducing a
- * genuinely new KIND of resolution fails HERE and forces a deliberate decision
- * about the public contract instead of leaking an internal name. */
-TEST(trace_evidence_strategy_class_vocabulary_is_closed) {
-    /* Every strategy string assigned anywhere in src/ + internal/ as of this
-     * commit, plus the two literals pass_calls.c writes directly. */
-    static const char *const lsp[] = {
-        "lsp_direct",         "lsp_base_dispatch",      "lsp_embed_dispatch",
-        "lsp_implicit_this",  "lsp_inherited_dispatch", "lsp_method_dispatch",
-        "lsp_proc_macro",     "lsp_smart_ptr_dispatch", "lsp_strategy_cross_file",
-        "lsp_trait_dispatch", "lsp_type_dispatch",      "lsp_virtual_dispatch"};
-    for (size_t i = 0; i < sizeof(lsp) / sizeof(lsp[0]); i++) {
-        const char *cls = cbm_mcp_edge_strategy_class(lsp[i]);
-        ASSERT_NOT_NULL(cls);
-        ASSERT_STR_EQ(cls, "lsp");
-    }
-    static const char *const lang[] = {"php_self_static", "php_static_resolved",
-                                       "perl_method_static", "perl_method_typed"};
-    for (size_t i = 0; i < sizeof(lang) / sizeof(lang[0]); i++) {
-        const char *cls = cbm_mcp_edge_strategy_class(lang[i]);
-        ASSERT_NOT_NULL(cls);
-        ASSERT_STR_EQ(cls, "language_rule");
-    }
-    static const char *const heur[] = {"callee_suffix", "field_type_hint", "service_pattern",
-                                       "fastapi_depends"};
-    for (size_t i = 0; i < sizeof(heur) / sizeof(heur[0]); i++) {
-        const char *cls = cbm_mcp_edge_strategy_class(heur[i]);
-        ASSERT_NOT_NULL(cls);
-        ASSERT_STR_EQ(cls, "heuristic");
-    }
-    /* A failed LSP resolution is reported as unresolved, not as "lsp" — the
-     * caller's question is whether the edge is trustworthy, and "we tried LSP
-     * and it did not resolve" answers no. */
-    ASSERT_STR_EQ(cbm_mcp_edge_strategy_class("lsp_unresolved"), "unresolved");
-    ASSERT_STR_EQ(cbm_mcp_edge_strategy_class("unknown"), "unresolved");
-    /* Only a NULL/empty strategy is unclassified — an unmapped non-empty value
-     * must never silently disappear from the output. */
-    ASSERT_NULL(cbm_mcp_edge_strategy_class(NULL));
-    ASSERT_NULL(cbm_mcp_edge_strategy_class(""));
-    ASSERT_STR_EQ(cbm_mcp_edge_strategy_class("some_future_resolver"), "heuristic");
-    PASS();
-}
-
-/* Distilled from #559 (@vvenegasv). The indexer already records
- * {strategy, confidence} on every CALLS edge (pass_calls.c:355) and the store
- * reads it back, but no tool ever surfaced it — an agent could see THAT A->B
- * exists, never HOW it was resolved.
- *
- * Binds two things at once: the evidence columns appear only when asked for
- * (default stays lean), and the published value is the CLASS, not the raw
- * internal strategy name. Fails without the production change in both
- * directions — no columns at all before, and "lsp_trait_dispatch" would leak
- * verbatim if the classifier were bypassed. */
-TEST(tool_trace_path_evidence_is_opt_in_and_class_mapped) {
+/* Reproduce-first for #640: query handlers must accept the `project_name`
+ * alias, not only the canonical `project` key. list_projects surfaces the field
+ * as "name" and the error hint says "pass the project name", so a caller
+ * naturally passes `project_name`. With no alias, the handler reads key
+ * "project" -> NULL -> resolve_store bails before opening any .db -> "project
+ * not found or not indexed" even though the project is indexed. Mirrors
+ * tool_get_architecture_emits_populated_sections but with the alias key. */
+TEST(tool_get_architecture_accepts_project_name_alias_issue640) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
     cbm_store_t *st = cbm_mcp_server_store(srv);
-    const char *proj = "ev-proj";
+    ASSERT_NOT_NULL(st);
+
+    const char *proj = "alias640";
     cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/ev");
-    cbm_node_t caller = {.project = proj,
-                         .label = "Function",
-                         .name = "caller",
-                         .qualified_name = "ev-proj.src.caller",
-                         .file_path = "src/a.c",
-                         .start_line = 1,
-                         .end_line = 5};
-    cbm_node_t callee = {.project = proj,
-                         .label = "Function",
-                         .name = "target",
-                         .qualified_name = "ev-proj.src.target",
-                         .file_path = "src/a.c",
-                         .start_line = 10,
-                         .end_line = 20};
-    int64_t id_caller = cbm_store_upsert_node(st, &caller);
-    int64_t id_callee = cbm_store_upsert_node(st, &callee);
-    ASSERT_GT(id_caller, 0);
-    ASSERT_GT(id_callee, 0);
-    /* Exactly the shape pass_calls.c:355 writes in production. */
-    cbm_edge_t e = {.project = proj,
-                    .source_id = id_caller,
-                    .target_id = id_callee,
-                    .type = "CALLS",
-                    .properties_json = "{\"callee\":\"target\",\"confidence\":0.95,"
-                                       "\"strategy\":\"lsp_trait_dispatch\",\"candidates\":1}"};
-    ASSERT_GT(cbm_store_insert_edge(st, &e), 0);
+    cbm_store_upsert_project(st, proj, "/tmp/alias640");
 
-    /* Default: lean. No evidence columns, no strategy anywhere. */
-    char *plain = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":91,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"trace_path\",\"arguments\":{\"function_name\":\"caller\","
-             "\"project\":\"ev-proj\",\"direction\":\"outbound\"}}}");
-    ASSERT_NOT_NULL(plain);
-    char *plain_txt = extract_text_content(plain);
-    ASSERT_NOT_NULL(plain_txt);
-    ASSERT_NOT_NULL(strstr(plain_txt, "target")); /* positive control: the hop IS there */
-    ASSERT_NULL(strstr(plain_txt, "lsp"));
-    ASSERT_NULL(strstr(plain_txt, "0.95"));
-    free(plain_txt);
-    free(plain);
+    cbm_node_t main_fn = {0};
+    main_fn.project = proj;
+    main_fn.label = "Function";
+    main_fn.name = "main";
+    main_fn.qualified_name = "alias640.cmd.main";
+    main_fn.file_path = "cmd/main.go";
+    main_fn.start_line = 1;
+    main_fn.end_line = 3;
+    main_fn.properties_json = "{\"is_entry_point\":true}";
+    ASSERT_GT(cbm_store_upsert_node(st, &main_fn), 0);
 
-    /* Opted in: the class and the confidence appear, the raw name does not. */
-    char *ev = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":92,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"trace_path\",\"arguments\":{\"function_name\":\"caller\","
-             "\"project\":\"ev-proj\",\"direction\":\"outbound\",\"include_evidence\":true}}}");
-    ASSERT_NOT_NULL(ev);
-    char *ev_txt = extract_text_content(ev);
-    ASSERT_NOT_NULL(ev_txt);
-    ASSERT_NOT_NULL(strstr(ev_txt, "target"));
-    ASSERT_NOT_NULL(strstr(ev_txt, "lsp"));
-    ASSERT_NOT_NULL(strstr(ev_txt, "0.95"));
-    /* The internal resolver name must NOT reach the client. */
-    ASSERT_NULL(strstr(ev_txt, "lsp_trait_dispatch"));
-    free(ev_txt);
-    free(ev);
+    /* Caller passes `project_name` (the natural guess) instead of `project`. */
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":640,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"get_architecture\","
+             "\"arguments\":{\"project_name\":\"alias640\",\"aspects\":[\"all\"]}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
 
-    /* #1542: the same request with format:"json" returned cols ["name","hop"]
-     * — include_evidence was implemented on the tree path only, so the callers
-     * most likely to ask for structured output were the ones who silently got
-     * nothing. The two formats must promise the same fields. */
-    char *ev_json = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":93,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"trace_path\",\"arguments\":{\"function_name\":\"caller\","
-             "\"project\":\"ev-proj\",\"direction\":\"outbound\",\"include_evidence\":true,"
-             "\"format\":\"json\"}}}");
-    ASSERT_NOT_NULL(ev_json);
-    char *ev_json_txt = extract_text_content(ev_json);
-    ASSERT_NOT_NULL(ev_json_txt);
-    ASSERT_NOT_NULL(strstr(ev_json_txt, "\"strategy\""));
-    ASSERT_NOT_NULL(strstr(ev_json_txt, "\"confidence\""));
-    ASSERT_NOT_NULL(strstr(ev_json_txt, "lsp"));
-    ASSERT_NOT_NULL(strstr(ev_json_txt, "0.95"));
-    ASSERT_NULL(strstr(ev_json_txt, "lsp_trait_dispatch"));
-    free(ev_json_txt);
-    free(ev_json);
+    /* RED before the alias: inner is the "project not found" error.
+     * GREEN after: the alias resolves and architecture sections surface. */
+    ASSERT_NULL(strstr(inner, "project not found"));
+    ASSERT_NOT_NULL(strstr(inner, "entry_points:"));
+
+    free(inner);
+    free(resp);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Reproduce-first (#887): the client-supplied `depth` on trace_call_path must be
- * clamped to the MCP ceiling (cbm_mcp_max_depth(), default 15). On origin/main
- * an MCP_MAX_DEPTH=15 constant was defined but never applied — `depth` flowed
- * straight into bfs_union_same_name, so an unbounded value drives the shared
- * cbm_store_bfs to arbitrary depth. Over an 18-node call chain, depth=1000
- * reaches n16/n17 (RED); with the clamp the walk stops at hop 15, so n15 is
- * reached but n16 is not (GREEN). Quoted tokens ("n15"/"n16") match only the
- * node-name field, never the qualified_name (preceded by '.'), so the boundary
- * check is exact. */
-TEST(tool_trace_call_path_depth_clamped) {
+/* Reproduce-first for #640: the alias must apply across query handlers, not
+ * just get_architecture. search_graph with `project_name` must resolve too. */
+TEST(tool_search_graph_accepts_project_name_alias_issue640) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
     cbm_store_t *st = cbm_mcp_server_store(srv);
-    const char *proj = "depth-proj";
+    ASSERT_NOT_NULL(st);
+
+    const char *proj = "alias640b";
     cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/depth");
+    cbm_store_upsert_project(st, proj, "/tmp/alias640b");
 
-    /* Linear call chain n00 -CALLS-> n01 -> ... -> n17 (18 nodes). */
-    int64_t ids[18];
-    for (int i = 0; i < 18; i++) {
-        char name[8];
-        char qn[32];
-        snprintf(name, sizeof(name), "n%02d", i);
-        snprintf(qn, sizeof(qn), "depth-proj.n%02d", i);
-        cbm_node_t n = {.project = proj,
-                        .label = "Function",
-                        .name = name,
-                        .qualified_name = qn,
-                        .file_path = "chain.c",
-                        .start_line = 1,
-                        .end_line = 2};
-        ids[i] = cbm_store_upsert_node(st, &n);
-    }
-    for (int i = 0; i < 17; i++) {
-        cbm_edge_t e = {
-            .project = proj, .source_id = ids[i], .target_id = ids[i + 1], .type = "CALLS"};
-        cbm_store_insert_edge(st, &e);
-    }
+    cbm_node_t fn = {0};
+    fn.project = proj;
+    fn.label = "Function";
+    fn.name = "WidgetHandler";
+    fn.qualified_name = "alias640b.svc.WidgetHandler";
+    fn.file_path = "svc/widget.go";
+    fn.start_line = 1;
+    fn.end_line = 2;
+    ASSERT_GT(cbm_store_upsert_node(st, &fn), 0);
 
     char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":71,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"trace_call_path\",\"arguments\":{\"function_name\":\"n00\","
-             "\"project\":\"depth-proj\",\"direction\":\"outbound\",\"depth\":1000}}}");
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":641,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"search_graph\","
+             "\"arguments\":{\"project_name\":\"alias640b\",\"name_pattern\":\"Widget.*\"}}}");
     ASSERT_NOT_NULL(resp);
     char *inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
 
-    /* Reached within the ceiling (proves the traversal ran) but clamped at 15.
-     * TOON rows carry bare QNs, so match the names unquoted. */
-    ASSERT_NOT_NULL(strstr(inner, "n15"));
-    ASSERT_NULL(strstr(inner, "n16"));
+    ASSERT_NULL(strstr(inner, "project not found"));
+    ASSERT_NOT_NULL(strstr(inner, "WidgetHandler"));
 
     free(inner);
     free(resp);
@@ -3242,872 +7191,1657 @@ TEST(tool_trace_call_path_depth_clamped) {
     PASS();
 }
 
-/* Reproduce-first (#650, distilled): two GENUINELY-DIFFERENT same-named functions
- * whose bodies differ in length score differently, so the old exact-tie check did
- * not flag them ambiguous — and bfs_union_same_name (#546) then merged the caller
- * sets of both into one confidently-conflated answer (the mirror of #546's under-
- * report). The fix: 2+ real callable defs => ambiguous (disambiguate), never union
- * distinct symbols. RED before the pick_resolved_node real_def_count rule (response
- * merged callerA+callerB), GREEN after (response is ambiguous, no "callers"). */
-TEST(tool_trace_call_path_distinct_defs_not_over_unioned) {
+/* #1025: agents pass the repo FOLDER name ("codebase-memory-mcp"), but
+ * indexed project names derive from the full path
+ * (E:\project\graph\x -> "E-project-graph-x"), so exact lookup fails with
+ * "project not found" while list_projects clearly shows the project. A
+ * passed name that matches exactly ONE indexed project as a segment-aligned
+ * tail ("-<name>" suffix) must resolve to it; zero or several matches keep
+ * the existing error. Runs against real cache-dir .db files (the resolution
+ * scans filenames), so this test indexes real fixtures under an overridden
+ * CBM_CACHE_DIR. */
+static void i1025_write_repo(const char *dir, const char *fn_name) {
+    char path[CBM_SZ_512];
+    snprintf(path, sizeof(path), "%s/mod.py", dir);
+    FILE *f = fopen(path, "w");
+    if (!f)
+        return;
+    fprintf(f, "def %s(x):\n    return x + 1\n", fn_name);
+    fclose(f);
+}
+
+TEST(tool_project_arg_resolves_unique_tail_issue1025) {
+    char repo_a[CBM_SZ_256];
+    char repo_b[CBM_SZ_256];
+    char repo_c[CBM_SZ_256];
+    char cache[CBM_SZ_256];
+    snprintf(repo_a, sizeof(repo_a), "/tmp/cbm-i1025a-XXXXXX");
+    snprintf(repo_b, sizeof(repo_b), "/tmp/cbm-i1025b-XXXXXX");
+    snprintf(repo_c, sizeof(repo_c), "/tmp/cbm-i1025c-XXXXXX");
+    snprintf(cache, sizeof(cache), "/tmp/cbm-i1025d-XXXXXX");
+    if (!cbm_mkdtemp(repo_a) || !cbm_mkdtemp(repo_b) || !cbm_mkdtemp(repo_c) ||
+        !cbm_mkdtemp(cache)) {
+        FAIL("mkdtemp failed");
+    }
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? cbm_strdup(saved_cache) : NULL;
+    cbm_setenv("CBM_CACHE_DIR", cache, 1);
+    cbm_setenv("CBM_INDEX_SUPERVISOR", "0", 1);
+
+    i1025_write_repo(repo_a, "unique_tail_target");
+    i1025_write_repo(repo_b, "amb_one");
+    i1025_write_repo(repo_c, "amb_two");
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
+    char args[CBM_SZ_1K];
+    snprintf(args, sizeof(args), "{\"repo_path\":\"%s\",\"name\":\"E-project-graph-suffix1025\"}",
+             repo_a);
+    char *r = cbm_mcp_handle_tool(srv, "index_repository", args);
+    ASSERT_NOT_NULL(r);
+    free(r);
+    snprintf(args, sizeof(args), "{\"repo_path\":\"%s\",\"name\":\"F-alpha-amb1025\"}", repo_b);
+    r = cbm_mcp_handle_tool(srv, "index_repository", args);
+    ASSERT_NOT_NULL(r);
+    free(r);
+    snprintf(args, sizeof(args), "{\"repo_path\":\"%s\",\"name\":\"G-beta-amb1025\"}", repo_c);
+    r = cbm_mcp_handle_tool(srv, "index_repository", args);
+    ASSERT_NOT_NULL(r);
+    free(r);
+
+    /* 1. Unique tail resolves (RED today: "project not found"). */
+    r = cbm_mcp_handle_tool(srv, "search_graph",
+                            "{\"project\":\"suffix1025\",\"name_pattern\":\".*target.*\"}");
+    ASSERT_NOT_NULL(r);
+    if (strstr(r, "project not found")) {
+        fprintf(stderr, "  [1025] FAIL unique tail did not resolve: %.200s\n", r);
+    }
+    ASSERT_NULL(strstr(r, "project not found"));
+    ASSERT_NOT_NULL(strstr(r, "unique_tail_target"));
+    free(r);
+
+    /* 2. Ambiguous tail stays an error (never guess between projects). */
+    r = cbm_mcp_handle_tool(srv, "search_graph",
+                            "{\"project\":\"amb1025\",\"name_pattern\":\".*\"}");
+    ASSERT_NOT_NULL(r);
+    ASSERT_NOT_NULL(strstr(r, "project not found"));
+    free(r);
+
+    /* 3. Exact full name keeps working unchanged. */
+    r = cbm_mcp_handle_tool(srv, "search_graph",
+                            "{\"project\":\"E-project-graph-suffix1025\","
+                            "\"name_pattern\":\".*target.*\"}");
+    ASSERT_NOT_NULL(r);
+    ASSERT_NULL(strstr(r, "project not found"));
+    free(r);
+
+    cbm_mcp_server_free(srv);
+    if (saved_cache_copy) {
+        cbm_setenv("CBM_CACHE_DIR", saved_cache_copy, 1);
+        free(saved_cache_copy);
+    } else {
+        cbm_unsetenv("CBM_CACHE_DIR");
+    }
+    th_rmtree(repo_a);
+    th_rmtree(repo_b);
+    th_rmtree(repo_c);
+    th_rmtree(cache);
+    PASS();
+}
+
+/* Regression for #604: path scopes architecture totals and content. */
+TEST(tool_get_architecture_path_scoping) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
     cbm_store_t *st = cbm_mcp_server_store(srv);
-    const char *proj = "ou-proj";
+    ASSERT_NOT_NULL(st);
+
+    const char *proj = "arch-path";
     cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/ou");
-    /* two unrelated real definitions of "dupreal", DIFFERENT body spans */
-    cbm_node_t da = {.project = proj,
-                     .label = "Function",
-                     .name = "dupreal",
-                     .qualified_name = "ou-proj.a.dupreal",
-                     .file_path = "a.c",
-                     .start_line = 10,
-                     .end_line = 20}; /* span 10 */
-    cbm_node_t db = {.project = proj,
-                     .label = "Function",
-                     .name = "dupreal",
-                     .qualified_name = "ou-proj.b.dupreal",
-                     .file_path = "b.c",
-                     .start_line = 10,
-                     .end_line = 40}; /* span 30 (no tie) */
-    cbm_node_t ca = {.project = proj,
-                     .label = "Function",
-                     .name = "callerA",
-                     .qualified_name = "ou-proj.a.callerA",
-                     .file_path = "a.c",
-                     .start_line = 30,
-                     .end_line = 40};
-    cbm_node_t cb = {.project = proj,
-                     .label = "Function",
-                     .name = "callerB",
-                     .qualified_name = "ou-proj.b.callerB",
-                     .file_path = "b.c",
-                     .start_line = 50,
-                     .end_line = 60};
-    int64_t id_da = cbm_store_upsert_node(st, &da);
-    int64_t id_db = cbm_store_upsert_node(st, &db);
-    int64_t id_ca = cbm_store_upsert_node(st, &ca);
-    int64_t id_cb = cbm_store_upsert_node(st, &cb);
-    ASSERT_GT(id_da, 0);
-    ASSERT_GT(id_db, 0);
-    ASSERT_GT(id_ca, 0);
-    ASSERT_GT(id_cb, 0);
-    cbm_edge_t ea = {.project = proj, .source_id = id_ca, .target_id = id_da, .type = "CALLS"};
-    cbm_edge_t eb = {.project = proj, .source_id = id_cb, .target_id = id_db, .type = "CALLS"};
-    cbm_store_insert_edge(st, &ea);
-    cbm_store_insert_edge(st, &eb);
+    cbm_store_upsert_project(st, proj, "/tmp/arch-path");
+
+    cbm_node_t pkg_global = {.project = proj,
+                             .label = "Package",
+                             .name = "Django",
+                             .qualified_name = "arch-path.Django",
+                             .file_path = "vendor/django/__init__.py"};
+    cbm_store_upsert_node(st, &pkg_global);
+
+    cbm_node_t pkg_local = {.project = proj,
+                            .label = "Package",
+                            .name = "hoa",
+                            .qualified_name = "arch-path.hoa",
+                            .file_path = "apps/hoa/main.go"};
+    cbm_store_upsert_node(st, &pkg_local);
+
+    cbm_node_t f_hoa = {.project = proj,
+                        .label = "File",
+                        .name = "main.go",
+                        .qualified_name = "arch-path.apps.hoa.main.go",
+                        .file_path = "apps/hoa/main.go"};
+    cbm_store_upsert_node(st, &f_hoa);
+
+    cbm_node_t f_other = {.project = proj,
+                          .label = "File",
+                          .name = "other.go",
+                          .qualified_name = "arch-path.other.go",
+                          .file_path = "lib/other.go"};
+    cbm_store_upsert_node(st, &f_other);
+
+    char *resp_root = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":92,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"get_architecture\","
+             "\"arguments\":{\"project\":\"arch-path\",\"aspects\":[\"packages\"]}}}");
+    ASSERT_NOT_NULL(resp_root);
+    char *inner_root = extract_text_content(resp_root);
+    ASSERT_NOT_NULL(inner_root);
+    ASSERT_NOT_NULL(strstr(inner_root, "Django"));
+
+    char *resp_scoped =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":93,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"get_architecture\","
+                                   "\"arguments\":{\"project\":\"arch-path\",\"path\":\"apps/hoa\","
+                                   "\"aspects\":[\"packages\"]}}}");
+    ASSERT_NOT_NULL(resp_scoped);
+    char *inner_scoped = extract_text_content(resp_scoped);
+    ASSERT_NOT_NULL(inner_scoped);
+
+    ASSERT_NOT_NULL(strstr(inner_scoped, "root_total_nodes"));
+    ASSERT_NOT_NULL(strstr(inner_scoped, "scoped_total_nodes"));
+    ASSERT_NOT_NULL(strstr(inner_scoped, "path: "));
+    ASSERT_NOT_NULL(strstr(inner_scoped, "hoa"));
+    ASSERT_NULL(strstr(inner_scoped, "Django"));
+
+    int root_nodes = 0;
+    int scoped_nodes = 0;
+    /* TOON scalar form (`key: N`) with JSON fallback for format:"json". */
+    const char *rt = strstr(inner_scoped, "root_total_nodes: ");
+    const char *stn = strstr(inner_scoped, "scoped_total_nodes: ");
+    if (rt) {
+        sscanf(rt, "root_total_nodes: %d", &root_nodes);
+    } else if ((rt = strstr(inner_scoped, "\"root_total_nodes\":")) != NULL) {
+        sscanf(rt, "\"root_total_nodes\":%d", &root_nodes);
+    }
+    if (stn) {
+        sscanf(stn, "scoped_total_nodes: %d", &scoped_nodes);
+    } else if ((stn = strstr(inner_scoped, "\"scoped_total_nodes\":")) != NULL) {
+        sscanf(stn, "\"scoped_total_nodes\":%d", &scoped_nodes);
+    }
+    ASSERT_TRUE(root_nodes > scoped_nodes);
+    ASSERT_TRUE(scoped_nodes > 0);
 
-    char *resp = cbm_mcp_server_handle(
-        srv,
-        "{\"jsonrpc\":\"2.0\",\"id\":63,\"method\":\"tools/call\","
-        "\"params\":{\"name\":\"trace_call_path\",\"arguments\":{\"function_name\":\"dupreal\","
-        "\"project\":\"ou-proj\",\"direction\":\"inbound\"}}}");
-    ASSERT_NOT_NULL(resp);
-    char *inner = extract_text_content(resp);
-    ASSERT_NOT_NULL(inner);
-    /* distinct symbols must be disambiguated, not merged into one caller set */
-    ASSERT_NOT_NULL(strstr(inner, "ambiguous"));
-    ASSERT_NOT_NULL(strstr(inner, "suggestions"));
-    ASSERT_NULL(strstr(inner, "\"callers\""));
-    free(inner);
-    free(resp);
+    free(inner_scoped);
+    free(resp_scoped);
+    free(inner_root);
+    free(resp_root);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Guard that the ambiguity gate does NOT regress the #546 fix: a real .ts
- * implementation plus a body-less ambient .d.ts stub is ONE logical symbol
- * (one real callable def + a fragment), so it must stay non-ambiguous and the
- * caller sets from both nodes must be unioned. */
-TEST(tool_trace_call_path_dts_stub_unions_with_impl) {
+TEST(tool_query_graph_missing_query) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    const char *proj = "dts-proj";
-    cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/dts");
-    cbm_node_t impl = {.project = proj,
-                       .label = "Function",
-                       .name = "sym546",
-                       .qualified_name = "dts-proj.impl.sym546",
-                       .file_path = "src/sym.ts",
-                       .start_line = 10,
-                       .end_line = 30}; /* real body */
-    cbm_node_t stub = {.project = proj,
-                       .label = "Function",
-                       .name = "sym546",
-                       .qualified_name = "dts-proj.stub.sym546",
-                       .file_path = "types/sym.d.ts",
-                       .start_line = 5,
-                       .end_line = 5}; /* body-less ambient decl */
-    cbm_node_t crel = {.project = proj,
-                       .label = "Function",
-                       .name = "callerRel",
-                       .qualified_name = "dts-proj.callerRel",
-                       .file_path = "src/rel.ts",
-                       .start_line = 1,
-                       .end_line = 8};
-    cbm_node_t cali = {.project = proj,
-                       .label = "Function",
-                       .name = "callerAlias",
-                       .qualified_name = "dts-proj.callerAlias",
-                       .file_path = "src/ali.ts",
-                       .start_line = 1,
-                       .end_line = 8};
-    int64_t id_impl = cbm_store_upsert_node(st, &impl);
-    int64_t id_stub = cbm_store_upsert_node(st, &stub);
-    int64_t id_crel = cbm_store_upsert_node(st, &crel);
-    int64_t id_cali = cbm_store_upsert_node(st, &cali);
-    ASSERT_GT(id_impl, 0);
-    ASSERT_GT(id_stub, 0);
-    ASSERT_GT(id_crel, 0);
-    ASSERT_GT(id_cali, 0);
-    /* callers split by import style: relative -> impl, path-alias -> stub */
-    cbm_edge_t er = {.project = proj, .source_id = id_crel, .target_id = id_impl, .type = "CALLS"};
-    cbm_edge_t el = {.project = proj, .source_id = id_cali, .target_id = id_stub, .type = "CALLS"};
-    cbm_store_insert_edge(st, &er);
-    cbm_store_insert_edge(st, &el);
 
-    char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":64,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"trace_call_path\",\"arguments\":{\"function_name\":\"sym546\","
-             "\"project\":\"dts-proj\",\"direction\":\"inbound\"}}}");
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":23,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"query_graph\","
+                                   "\"arguments\":{}}}");
     ASSERT_NOT_NULL(resp);
-    char *inner = extract_text_content(resp);
-    ASSERT_NOT_NULL(inner);
-    ASSERT_NULL(strstr(inner, "ambiguous"));
-    /* union across impl + stub: BOTH callers appear (this is the #546 fix) */
-    ASSERT_NOT_NULL(strstr(inner, "callerRel"));
-    ASSERT_NOT_NULL(strstr(inner, "callerAlias"));
-    free(inner);
+    /* Should return error about missing query */
+    ASSERT_NOT_NULL(strstr(resp, "required"));
     free(resp);
+
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-TEST(tool_delete_project_not_found) {
+/* ══════════════════════════════════════════════════════════════════
+ *  PIPELINE-DEPENDENT TOOL HANDLERS
+ * ══════════════════════════════════════════════════════════════════ */
+
+TEST(tool_index_repository_missing_path) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
 
     char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":22,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"delete_project\","
-                                   "\"arguments\":{\"project\":\"nonexistent\"}}}");
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":30,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"index_repository\","
+                                   "\"arguments\":{}}}");
     ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "not_found"));
+    ASSERT_NOT_NULL(strstr(resp, "required"));
     free(resp);
 
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-TEST(tool_delete_project_mutation_guard_blocks_then_releases) {
-    char cache[256];
-    snprintf(cache, sizeof(cache), "/tmp/cbm-mcp-delete-guard-XXXXXX");
-    if (!cbm_mkdtemp(cache)) {
-        PASS();
-    }
-
-    const char *saved_cache = getenv("CBM_CACHE_DIR");
-    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
-    cbm_setenv("CBM_CACHE_DIR", cache, 1);
-
-    const char *project = "guard-delete-project";
-    char db_path[CBM_SZ_1K];
-    snprintf(db_path, sizeof(db_path), "%s/%s.db", cache, project);
-    cbm_store_t *setup = cbm_store_open_path(db_path);
-    ASSERT_NOT_NULL(setup);
-    ASSERT_EQ(cbm_store_upsert_project(setup, project, "/tmp/guard-delete-project"), CBM_STORE_OK);
-    cbm_store_close(setup);
-    ASSERT_TRUE(cbm_file_exists(db_path));
-
+TEST(tool_get_code_snippet_missing_qn) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    ASSERT_NOT_NULL(srv);
-    mcp_mutation_guard_probe_t probe = {.deny_begin_call = 1};
-    cbm_mcp_server_set_project_mutation_guard(srv, mcp_mutation_guard_probe_begin,
-                                              mcp_mutation_guard_probe_end, &probe);
 
     char *resp =
-        cbm_mcp_handle_tool(srv, "delete_project", "{\"project\":\"guard-delete-project\"}");
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "blocked"));
-    ASSERT_EQ(probe.begin_count, 1);
-    ASSERT_EQ(probe.end_count, 0);
-    ASSERT_STR_EQ(probe.begin_projects[0], project);
-    ASSERT_TRUE(cbm_file_exists(db_path));
-    free(resp);
-
-    probe.deny_begin_call = 0;
-    resp = cbm_mcp_handle_tool(srv, "delete_project", "{\"project\":\"guard-delete-project\"}");
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":31,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"get_code_snippet\","
+                                   "\"arguments\":{}}}");
     ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "deleted"));
-    ASSERT_EQ(probe.begin_count, 2);
-    ASSERT_EQ(probe.end_count, 1);
-    ASSERT_STR_EQ(probe.begin_projects[1], project);
-    ASSERT_STR_EQ(probe.end_projects[0], project);
-    ASSERT_FALSE(cbm_file_exists(db_path));
+    ASSERT_NOT_NULL(strstr(resp, "required"));
     free(resp);
 
     cbm_mcp_server_free(srv);
-    cleanup_project_db(cache, project);
-    cbm_rmdir(cache);
-    restore_cache_dir(saved_cache_copy);
-    free(saved_cache_copy);
     PASS();
 }
 
-TEST(tool_index_repository_mutation_guard_blocks_before_local_worker) {
-    char root[CBM_SZ_1K];
-    (void)snprintf(root, sizeof(root), "%s/cbm-index-guard-XXXXXX", cbm_tmpdir());
-    ASSERT_NOT_NULL(cbm_mkdtemp(root));
-
+TEST(tool_get_code_snippet_not_found) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    ASSERT_NOT_NULL(srv);
-    mcp_mutation_guard_probe_t probe = {.deny_begin_call = 1};
-    cbm_mcp_server_set_project_mutation_guard(srv, mcp_mutation_guard_probe_begin,
-                                              mcp_mutation_guard_probe_end, &probe);
-
-    char args[CBM_SZ_2K];
-    (void)snprintf(args, sizeof(args),
-                   "{\"repo_path\":\"%s\",\"name\":\"GuardedIndex\","
-                   "\"mode\":\"fast\"}",
-                   root);
-    int spawn_before = cbm_index_supervisor_spawn_count();
-    char *response = cbm_mcp_handle_tool(srv, "index_repository", args);
-    int spawn_after = cbm_index_supervisor_spawn_count();
 
-    ASSERT_NOT_NULL(response);
-    ASSERT_NOT_NULL(strstr(response, "blocked"));
-    ASSERT_EQ(probe.begin_count, 1);
-    ASSERT_EQ(probe.end_count, 0);
-    ASSERT_STR_EQ(probe.begin_projects[0], "GuardedIndex");
-    ASSERT_EQ(spawn_after, spawn_before);
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":32,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"get_code_snippet\","
+                                   "\"arguments\":{\"qualified_name\":\"nonexistent.func\","
+                                   "\"project\":\"nonexistent\"}}}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "not found"));
+    free(resp);
 
-    free(response);
     cbm_mcp_server_free(srv);
-    (void)th_rmtree(root);
     PASS();
 }
 
-TEST(tool_get_architecture_empty) {
+TEST(tool_search_code_missing_pattern) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
 
     char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":24,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"get_architecture\","
-                                   "\"arguments\":{\"project\":\"nonexistent\"}}}");
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":33,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"search_code\","
+                                   "\"arguments\":{}}}");
     ASSERT_NOT_NULL(resp);
-    /* No store for nonexistent project — should return project error */
-    ASSERT_TRUE(strstr(resp, "not found") || strstr(resp, "not indexed"));
+    ASSERT_NOT_NULL(strstr(resp, "required"));
     free(resp);
 
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Regression for #281: handle_get_architecture must actually call
- * cbm_store_get_architecture and surface its sections. Before the fix
- * only label/edge histograms were emitted regardless of which aspects
- * were requested. The store-side arch_entry_points query reads
- * properties.is_entry_point on Function nodes, so we tag one node and
- * assert the resulting JSON surfaces an "entry_points" array containing
- * the tagged function — which is impossible without the wiring. */
-TEST(tool_get_architecture_emits_populated_sections) {
+/* #1511 (distilled from @lukiod's #1512): search_code echoed a negative limit
+ * back as the result count — "results: -5" — which an agent reads as an answer,
+ * not as a rejected argument. Both halves matter: the schema declares the bound
+ * so well-behaved clients never send it, and the handler clamps because a
+ * schema is a request to the client, never a guarantee to the server. */
+TEST(tool_search_code_negative_limit_is_not_echoed_issue1511) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    ASSERT_NOT_NULL(srv);
-
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(st);
-
-    const char *proj = "arch-test";
-    cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/arch-test");
-
-    cbm_node_t main_fn = {0};
-    main_fn.project = proj;
-    main_fn.label = "Function";
-    main_fn.name = "main";
-    main_fn.qualified_name = "arch-test.cmd.main";
-    main_fn.file_path = "cmd/main.go";
-    main_fn.start_line = 1;
-    main_fn.end_line = 3;
-    main_fn.properties_json = "{\"is_entry_point\":true}";
-    ASSERT_GT(cbm_store_upsert_node(st, &main_fn), 0);
-
-    char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":91,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"get_architecture\","
-             "\"arguments\":{\"project\":\"arch-test\",\"aspects\":[\"all\"]}}}");
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":35,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"search_code\","
+                                   "\"arguments\":{\"pattern\":\"func main\","
+                                   "\"project\":\"nonexistent\",\"limit\":-5}}}");
     ASSERT_NOT_NULL(resp);
-    char *inner = extract_text_content(resp);
-    ASSERT_NOT_NULL(inner);
-
-    /* The handler always emits node/edge counts and schema histograms;
-     * those existed before #281. The "entry_points" array only appears
-     * when cbm_store_get_architecture is actually called and its result
-     * is serialized — which is exactly what #281 wires up. */
-    ASSERT_NOT_NULL(strstr(inner, "entry_points:"));
-    ASSERT_NOT_NULL(strstr(inner, "main"));
-
-    free(inner);
+    ASSERT_NULL(strstr(resp, "results: -5"));
     free(resp);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Distills PR #560 (overview subset): "overview" must expand to a compact
- * subset — every aspect EXCEPT file_tree. Before the fix, "overview" was not
- * registered in either aspect gate (want_aspect in store.c, aspect_wanted in
- * mcp.c), so aspects=["overview"] silently degraded to just
- * {total_nodes,total_edges}. RED on unfixed code: no "entry_points" key. */
-TEST(tool_get_architecture_overview_compact_subset_pr560) {
+TEST(tool_search_code_limit_declares_a_minimum_issue1511) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    ASSERT_NOT_NULL(srv);
-
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(st);
-
-    const char *proj = "arch560";
-    cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/arch560");
-
-    cbm_node_t main_fn = {0};
-    main_fn.project = proj;
-    main_fn.label = "Function";
-    main_fn.name = "main";
-    main_fn.qualified_name = "arch560.cmd.main";
-    main_fn.file_path = "cmd/main.go";
-    main_fn.start_line = 1;
-    main_fn.end_line = 3;
-    main_fn.properties_json = "{\"is_entry_point\":true}";
-    ASSERT_GT(cbm_store_upsert_node(st, &main_fn), 0);
-
-    /* A File node so the file_tree aspect has real content — makes the
-     * "overview drops file_tree" assertion below non-vacuous. */
-    cbm_node_t file_node = {.project = proj,
-                            .label = "File",
-                            .name = "main.go",
-                            .qualified_name = "arch560.cmd.main.go",
-                            .file_path = "cmd/main.go"};
-    ASSERT_GT(cbm_store_upsert_node(st, &file_node), 0);
-
-    /* Sanity: with "all", both entry_points and file_tree surface. */
-    char *resp_all = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":560,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"get_architecture\","
-             "\"arguments\":{\"project\":\"arch560\",\"aspects\":[\"all\"]}}}");
-    ASSERT_NOT_NULL(resp_all);
-    char *inner_all = extract_text_content(resp_all);
-    ASSERT_NOT_NULL(inner_all);
-    ASSERT_NOT_NULL(strstr(inner_all, "entry_points:"));
-    ASSERT_NOT_NULL(strstr(inner_all, "file_tree:"));
-    free(inner_all);
-    free(resp_all);
-
-    /* "overview": substantive content (entry_points, node_labels) but NO
-     * file_tree section. */
     char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":561,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"get_architecture\","
-             "\"arguments\":{\"project\":\"arch560\",\"aspects\":[\"overview\"]}}}");
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":36,\"method\":\"tools/list\",\"params\":{}}");
     ASSERT_NOT_NULL(resp);
-    char *inner = extract_text_content(resp);
-    ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "entry_points:"));
-    ASSERT_NOT_NULL(strstr(inner, "node_labels:"));
-    ASSERT_NULL(strstr(inner, "file_tree:"));
 
-    free(inner);
+    yyjson_doc *doc = yyjson_read(resp, strlen(resp), 0);
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *result = root ? yyjson_obj_get(root, "result") : NULL;
+    yyjson_val *tools = result ? yyjson_obj_get(result, "tools") : NULL;
+    yyjson_val *minimum = NULL;
+    if (tools && yyjson_is_arr(tools)) {
+        size_t index, max;
+        yyjson_val *tool;
+        yyjson_arr_foreach(tools, index, max, tool) {
+            yyjson_val *name = yyjson_obj_get(tool, "name");
+            if (!name || !yyjson_is_str(name) || strcmp(yyjson_get_str(name), "search_code") != 0) {
+                continue;
+            }
+            yyjson_val *schema = yyjson_obj_get(tool, "inputSchema");
+            yyjson_val *props = schema ? yyjson_obj_get(schema, "properties") : NULL;
+            yyjson_val *limit = props ? yyjson_obj_get(props, "limit") : NULL;
+            minimum = limit ? yyjson_obj_get(limit, "minimum") : NULL;
+            break;
+        }
+    }
+    bool declared = minimum && yyjson_is_int(minimum) && yyjson_get_int(minimum) >= 1;
+    yyjson_doc_free(doc);
     free(resp);
     cbm_mcp_server_free(srv);
+
+    ASSERT_TRUE(declared);
     PASS();
 }
 
-/* Distills PR #560 (server-side validation): unknown aspect tokens must be
- * rejected with an isError result listing the valid values. Before the fix
- * the JSON-Schema accepted any string and both aspect gates simply never
- * matched, so a typo like "bogus_aspect" produced a silent near-empty payload
- * with isError:false. RED on unfixed code: no isError, no "Unknown aspect". */
-TEST(tool_get_architecture_rejects_unknown_aspect_pr560) {
+TEST(tool_search_code_declares_independent_result_and_raw_content_paging) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    ASSERT_NOT_NULL(srv);
-
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(st);
-
-    const char *proj = "arch560v";
-    cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/arch560v");
-
     char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":562,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"get_architecture\","
-             "\"arguments\":{\"project\":\"arch560v\",\"aspects\":[\"bogus_aspect\"]}}}");
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":37,\"method\":\"tools/list\",\"params\":{}}");
     ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "\"isError\":true"));
-    ASSERT_NOT_NULL(strstr(resp, "Unknown aspect 'bogus_aspect'"));
-    /* The error must teach the valid vocabulary, including the new token. */
-    ASSERT_NOT_NULL(strstr(resp, "overview"));
-    ASSERT_NOT_NULL(strstr(resp, "file_tree"));
 
+    yyjson_doc *doc = yyjson_read(resp, strlen(resp), 0);
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *result = root ? yyjson_obj_get(root, "result") : NULL;
+    yyjson_val *tools = result ? yyjson_obj_get(result, "tools") : NULL;
+    yyjson_val *props = NULL;
+    if (tools && yyjson_is_arr(tools)) {
+        size_t index, max;
+        yyjson_val *tool;
+        yyjson_arr_foreach(tools, index, max, tool) {
+            yyjson_val *name = yyjson_obj_get(tool, "name");
+            if (name && yyjson_is_str(name) && strcmp(yyjson_get_str(name), "search_code") == 0) {
+                yyjson_val *schema = yyjson_obj_get(tool, "inputSchema");
+                props = schema ? yyjson_obj_get(schema, "properties") : NULL;
+                break;
+            }
+        }
+    }
+    bool declared = props && yyjson_obj_get(props, "result_limit") &&
+                    yyjson_obj_get(props, "result_offset") &&
+                    yyjson_obj_get(props, "raw_content_offset");
+    yyjson_doc_free(doc);
     free(resp);
     cbm_mcp_server_free(srv);
+
+    ASSERT_TRUE(declared);
     PASS();
 }
 
-/* Reproduce-first for #640: query handlers must accept the `project_name`
- * alias, not only the canonical `project` key. list_projects surfaces the field
- * as "name" and the error hint says "pass the project name", so a caller
- * naturally passes `project_name`. With no alias, the handler reads key
- * "project" -> NULL -> resolve_store bails before opening any .db -> "project
- * not found or not indexed" even though the project is indexed. Mirrors
- * tool_get_architecture_emits_populated_sections but with the alias key. */
-TEST(tool_get_architecture_accepts_project_name_alias_issue640) {
+TEST(tool_search_code_no_project) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    ASSERT_NOT_NULL(srv);
-
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(st);
 
-    const char *proj = "alias640";
-    cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/alias640");
+    char *resp =
+        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":34,\"method\":\"tools/call\","
+                                   "\"params\":{\"name\":\"search_code\","
+                                   "\"arguments\":{\"pattern\":\"func main\","
+                                   "\"project\":\"nonexistent\"}}}");
+    ASSERT_NOT_NULL(resp);
+    /* No project indexed → error */
+    ASSERT_TRUE(strstr(resp, "not found") || strstr(resp, "not indexed") ||
+                strstr(resp, "required"));
+    free(resp);
 
-    cbm_node_t main_fn = {0};
-    main_fn.project = proj;
-    main_fn.label = "Function";
-    main_fn.name = "main";
-    main_fn.qualified_name = "alias640.cmd.main";
-    main_fn.file_path = "cmd/main.go";
-    main_fn.start_line = 1;
-    main_fn.end_line = 3;
-    main_fn.properties_json = "{\"is_entry_point\":true}";
-    ASSERT_GT(cbm_store_upsert_node(st, &main_fn), 0);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
 
-    /* Caller passes `project_name` (the natural guess) instead of `project`. */
-    char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":640,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"get_architecture\","
-             "\"arguments\":{\"project_name\":\"alias640\",\"aspects\":[\"all\"]}}}");
-    ASSERT_NOT_NULL(resp);
-    char *inner = extract_text_content(resp);
-    ASSERT_NOT_NULL(inner);
+TEST(search_code_multi_word) {
+    char tmp[512];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
 
-    /* RED before the alias: inner is the "project not found" error.
-     * GREEN after: the alias resolves and architecture sections surface. */
-    ASSERT_NULL(strstr(inner, "project not found"));
-    ASSERT_NOT_NULL(strstr(inner, "entry_points:"));
+    /* Multi-word query "HandleRequest error" — should find the line
+     * "func HandleRequest() error {" via regex conversion. */
+    char req[512];
+    snprintf(req, sizeof(req),
+             "{\"jsonrpc\":\"2.0\",\"id\":90,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"search_code\","
+             "\"arguments\":{\"pattern\":\"HandleRequest error\","
+             "\"project\":\"test-project\"}}}");
 
-    free(inner);
+    char *resp = cbm_mcp_server_handle(srv, req);
+    ASSERT_NOT_NULL(resp);
+    /* Should find at least one result (not zero) */
+    ASSERT_TRUE(strstr(resp, "HandleRequest") != NULL);
+    /* Should NOT contain an error about "not found" */
+    ASSERT_TRUE(strstr(resp, "\"isError\":true") == NULL);
     free(resp);
+
+    cleanup_snippet_dir(tmp);
     cbm_mcp_server_free(srv);
     PASS();
 }
 
-/* Reproduce-first for #640: the alias must apply across query handlers, not
- * just get_architecture. search_graph with `project_name` must resolve too. */
-TEST(tool_search_graph_accepts_project_name_alias_issue640) {
+TEST(search_code_preserves_valid_utf8_source) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_srch_utf8_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    char src_path[512];
+    snprintf(src_path, sizeof(src_path), "%s/unicode.c", tmp);
+    FILE *fp = cbm_fopen(src_path, "wb");
+    ASSERT_NOT_NULL(fp);
+    fputs("void unicode_needle(void) { /* Gr\xC3\xBC\xC3\x9F"
+          "e \xE4\xB8\x96\xE7\x95\x8C */ }\n",
+          fp);
+    fclose(fp);
+
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "search-utf8";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    cbm_node_t node = {.project = project,
+                       .label = "Function",
+                       .name = "unicode_needle",
+                       .qualified_name = "search-utf8.unicode_needle",
+                       .file_path = "unicode.c",
+                       .start_line = 1,
+                       .end_line = 1};
+    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
 
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(st);
+    char *response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"unicode_needle\",\"project\":\"search-utf8\","
+                            "\"mode\":\"full\",\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "Gr\xC3\xBC\xC3\x9F"
+                                  "e"));
+    ASSERT_NOT_NULL(strstr(inner, "\xE4\xB8\x96\xE7\x95\x8C"));
+    ASSERT_NULL(strstr(inner, "Gr??e"));
 
-    const char *proj = "alias640b";
-    cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/alias640b");
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    cbm_unlink(src_path);
+    cbm_rmdir(tmp);
+    PASS();
+}
 
-    cbm_node_t fn = {0};
-    fn.project = proj;
-    fn.label = "Function";
-    fn.name = "WidgetHandler";
-    fn.qualified_name = "alias640b.svc.WidgetHandler";
-    fn.file_path = "svc/widget.go";
-    fn.start_line = 1;
-    fn.end_line = 2;
-    ASSERT_GT(cbm_store_upsert_node(st, &fn), 0);
+TEST(search_code_scans_complete_stream_and_ranks_globally) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_srch_sat_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
 
-    char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":641,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"search_graph\","
-             "\"arguments\":{\"project_name\":\"alias640b\",\"name_pattern\":\"Widget.*\"}}}");
-    ASSERT_NOT_NULL(resp);
-    char *inner = extract_text_content(resp);
-    ASSERT_NOT_NULL(inner);
+    char low_path[512];
+    char noise_path[512];
+    char high_path[512];
+    snprintf(low_path, sizeof(low_path), "%s/a_low.c", tmp);
+    snprintf(noise_path, sizeof(noise_path), "%s/b_noise.c", tmp);
+    snprintf(high_path, sizeof(high_path), "%s/z_high.c", tmp);
+    ASSERT_EQ(th_write_file(low_path, "int COMPLETE_SCAN_NEEDLE_low = 1;\n"), 0);
+    FILE *fp = cbm_fopen(noise_path, "wb");
+    ASSERT_NOT_NULL(fp);
+    for (int i = 1; i <= 500; i++) {
+        fprintf(fp, "int COMPLETE_SCAN_NEEDLE_noise_%d = %d;\n", i, i);
+    }
+    fputs("int sentinel = 0;\n", fp);
+    fclose(fp);
+    ASSERT_EQ(th_write_file(high_path, "int COMPLETE_SCAN_NEEDLE_high = 1;\n"), 0);
 
-    ASSERT_NULL(strstr(inner, "project not found"));
-    ASSERT_NOT_NULL(strstr(inner, "WidgetHandler"));
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "search-saturation";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    cbm_node_t nodes[] = {
+        {.project = project,
+         .label = "Function",
+         .name = "low",
+         .qualified_name = "search-saturation.low",
+         .file_path = "a_low.c",
+         .start_line = 1,
+         .end_line = 1},
+        /* Keep the noise file in the scoped file list without classifying its
+         * 500 matching lines to a graph node. */
+        {.project = project,
+         .label = "Variable",
+         .name = "sentinel",
+         .qualified_name = "search-saturation.sentinel",
+         .file_path = "b_noise.c",
+         .start_line = 501,
+         .end_line = 501},
+        {.project = project,
+         .label = "Route",
+         .name = "high",
+         .qualified_name = "search-saturation.high",
+         .file_path = "z_high.c",
+         .start_line = 1,
+         .end_line = 1},
+    };
+    for (size_t i = 0; i < sizeof(nodes) / sizeof(nodes[0]); i++) {
+        ASSERT_GT(cbm_store_upsert_node(store, &nodes[i]), 0);
+    }
+
+    for (int attempt = 0; attempt < 3; attempt++) {
+        char *resp = cbm_mcp_handle_tool(
+            srv, "search_code",
+            "{\"pattern\":\"COMPLETE_SCAN_NEEDLE\",\"project\":\"search-saturation\","
+            "\"result_limit\":1,\"raw_limit\":1,\"max_output_tokens\":10000,"
+            "\"format\":\"json\"}");
+        char *inner = extract_text_content(resp);
+        yyjson_doc *doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+        yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+        yyjson_val *rows = root ? yyjson_obj_get(root, "rows") : NULL;
+        yyjson_val *first = rows ? yyjson_arr_get(rows, 0) : NULL;
+        bool complete_and_globally_ranked =
+            root && first && yyjson_get_int(yyjson_obj_get(root, "total_grep_matches")) == 502 &&
+            strcmp(yyjson_get_str(yyjson_obj_get(root, "total_relation")), "eq") == 0 &&
+            yyjson_obj_get(root, "scan_saturated") == NULL &&
+            yyjson_get_int(yyjson_obj_get(root, "total_results")) == 2 &&
+            strcmp(yyjson_get_str(yyjson_arr_get(first, 0)), "search-saturation.high") == 0 &&
+            yyjson_get_int(yyjson_obj_get(root, "raw_match_count")) == 500 &&
+            yyjson_get_int(yyjson_obj_get(root, "raw_next_offset")) == 1;
+        yyjson_doc_free(doc);
+        free(inner);
+        free(resp);
+        ASSERT_TRUE(complete_and_globally_ranked);
+    }
 
+    char *resp = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"COMPLETE_SCAN_NEEDLE\",\"project\":\"search-saturation\","
+        "\"result_limit\":1,\"raw_limit\":1,\"raw_offset\":499,"
+        "\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *inner = extract_text_content(resp);
+    yyjson_doc *doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *raw_object = root ? yyjson_obj_get(root, "raw_matches") : NULL;
+    yyjson_val *raw_rows = raw_object ? yyjson_obj_get(raw_object, "rows") : NULL;
+    yyjson_val *last_raw = raw_rows ? yyjson_arr_get(raw_rows, 0) : NULL;
+    bool last_raw_reachable =
+        root && last_raw && strcmp(yyjson_get_str(yyjson_arr_get(last_raw, 0)), "b_noise.c") == 0 &&
+        yyjson_get_int(yyjson_arr_get(last_raw, 1)) == 500 &&
+        !yyjson_get_bool(yyjson_obj_get(root, "raw_has_more"));
+    yyjson_doc_free(doc);
     free(inner);
     free(resp);
     cbm_mcp_server_free(srv);
+    ASSERT_EQ(th_rmtree(tmp), 0);
+    ASSERT_TRUE(last_raw_reachable);
     PASS();
 }
 
-/* #1025: agents pass the repo FOLDER name ("codebase-memory-mcp"), but
- * indexed project names derive from the full path
- * (E:\project\graph\x -> "E-project-graph-x"), so exact lookup fails with
- * "project not found" while list_projects clearly shows the project. A
- * passed name that matches exactly ONE indexed project as a segment-aligned
- * tail ("-<name>" suffix) must resolve to it; zero or several matches keep
- * the existing error. Runs against real cache-dir .db files (the resolution
- * scans filenames), so this test indexes real fixtures under an overridden
- * CBM_CACHE_DIR. */
-static void i1025_write_repo(const char *dir, const char *fn_name) {
-    char path[CBM_SZ_512];
-    snprintf(path, sizeof(path), "%s/mod.py", dir);
-    FILE *f = fopen(path, "w");
-    if (!f)
-        return;
-    fprintf(f, "def %s(x):\n    return x + 1\n", fn_name);
-    fclose(f);
-}
-
-TEST(tool_project_arg_resolves_unique_tail_issue1025) {
-    char repo_a[CBM_SZ_256];
-    char repo_b[CBM_SZ_256];
-    char repo_c[CBM_SZ_256];
-    char cache[CBM_SZ_256];
-    snprintf(repo_a, sizeof(repo_a), "/tmp/cbm-i1025a-XXXXXX");
-    snprintf(repo_b, sizeof(repo_b), "/tmp/cbm-i1025b-XXXXXX");
-    snprintf(repo_c, sizeof(repo_c), "/tmp/cbm-i1025c-XXXXXX");
-    snprintf(cache, sizeof(cache), "/tmp/cbm-i1025d-XXXXXX");
-    if (!cbm_mkdtemp(repo_a) || !cbm_mkdtemp(repo_b) || !cbm_mkdtemp(repo_c) ||
-        !cbm_mkdtemp(cache)) {
-        FAIL("mkdtemp failed");
-    }
-    const char *saved_cache = getenv("CBM_CACHE_DIR");
-    char *saved_cache_copy = saved_cache ? cbm_strdup(saved_cache) : NULL;
-    cbm_setenv("CBM_CACHE_DIR", cache, 1);
-    cbm_setenv("CBM_INDEX_SUPERVISOR", "0", 1);
-
-    i1025_write_repo(repo_a, "unique_tail_target");
-    i1025_write_repo(repo_b, "amb_one");
-    i1025_write_repo(repo_c, "amb_two");
+TEST(search_code_fails_closed_when_complete_scan_is_impossible) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "%s/cbm_srch_incomplete_XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
 
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-incomplete";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
 
-    char args[CBM_SZ_1K];
-    snprintf(args, sizeof(args), "{\"repo_path\":\"%s\",\"name\":\"E-project-graph-suffix1025\"}",
-             repo_a);
-    char *r = cbm_mcp_handle_tool(srv, "index_repository", args);
-    ASSERT_NOT_NULL(r);
-    free(r);
-    snprintf(args, sizeof(args), "{\"repo_path\":\"%s\",\"name\":\"F-alpha-amb1025\"}", repo_b);
-    r = cbm_mcp_handle_tool(srv, "index_repository", args);
-    ASSERT_NOT_NULL(r);
-    free(r);
-    snprintf(args, sizeof(args), "{\"repo_path\":\"%s\",\"name\":\"G-beta-amb1025\"}", repo_c);
-    r = cbm_mcp_handle_tool(srv, "index_repository", args);
-    ASSERT_NOT_NULL(r);
-    free(r);
-
-    /* 1. Unique tail resolves (RED today: "project not found"). */
-    r = cbm_mcp_handle_tool(srv, "search_graph",
-                            "{\"project\":\"suffix1025\",\"name_pattern\":\".*target.*\"}");
-    ASSERT_NOT_NULL(r);
-    if (strstr(r, "project not found")) {
-        fprintf(stderr, "  [1025] FAIL unique tail did not resolve: %.200s\n", r);
-    }
-    ASSERT_NULL(strstr(r, "project not found"));
-    ASSERT_NOT_NULL(strstr(r, "unique_tail_target"));
-    free(r);
-
-    /* 2. Ambiguous tail stays an error (never guess between projects). */
-    r = cbm_mcp_handle_tool(srv, "search_graph",
-                            "{\"project\":\"amb1025\",\"name_pattern\":\".*\"}");
-    ASSERT_NOT_NULL(r);
-    ASSERT_NOT_NULL(strstr(r, "project not found"));
-    free(r);
+    /* The graph snapshot names a file that is no longer readable by grep.
+     * Returning zero exact matches would be a false completeness claim. */
+    cbm_node_t missing = {.project = project,
+                          .label = "Function",
+                          .name = "missing",
+                          .qualified_name = "search-incomplete.missing",
+                          .file_path = "missing.c",
+                          .start_line = 1,
+                          .end_line = 1};
+    ASSERT_GT(cbm_store_upsert_node(store, &missing), 0);
 
-    /* 3. Exact full name keeps working unchanged. */
-    r = cbm_mcp_handle_tool(srv, "search_graph",
-                            "{\"project\":\"E-project-graph-suffix1025\","
-                            "\"name_pattern\":\".*target.*\"}");
-    ASSERT_NOT_NULL(r);
-    ASSERT_NULL(strstr(r, "project not found"));
-    free(r);
+    char *response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"NEVER_SCANNED\",\"project\":\"search-incomplete\","
+                            "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    ASSERT_NOT_NULL(strstr(response, "\"isError\":true"));
+    ASSERT_NOT_NULL(strstr(response, "complete result set was scanned"));
 
+    free(response);
     cbm_mcp_server_free(srv);
-    if (saved_cache_copy) {
-        cbm_setenv("CBM_CACHE_DIR", saved_cache_copy, 1);
-        free(saved_cache_copy);
-    } else {
-        cbm_unsetenv("CBM_CACHE_DIR");
-    }
-    th_rmtree(repo_a);
-    th_rmtree(repo_b);
-    th_rmtree(repo_c);
-    th_rmtree(cache);
+    ASSERT_EQ(th_rmtree(tmp), 0);
     PASS();
 }
 
-/* Regression for #604: path scopes architecture totals and content. */
-TEST(tool_get_architecture_path_scoping) {
+TEST(search_code_scoped_scan_uses_canonical_file_nodes) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "%s/cbm_srch_folder_XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+
+    char source_dir[512];
+    char source_path[640];
+    snprintf(source_dir, sizeof(source_dir), "%s/src", tmp);
+    snprintf(source_path, sizeof(source_path), "%s/main.c", source_dir);
+    ASSERT_EQ(cbm_mkdir(source_dir), 0);
+    ASSERT_EQ(th_write_file(source_path, "int FOLDER_SCOPE_NEEDLE = 1;\n"), 0);
+
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-folder-scope";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+
+    /* Graph-only nodes may carry directory or synthetic file_path identities.
+     * Neither belongs in the content scanner's canonical File-node set. */
+    cbm_node_t folder = {.project = project,
+                         .label = "Folder",
+                         .name = "src",
+                         .qualified_name = "search-folder-scope.src",
+                         .file_path = "src"};
+    cbm_node_t builtin = {.project = project,
+                          .label = "Function",
+                          .name = "len",
+                          .qualified_name = "builtins.len",
+                          .file_path = "<python-builtins>",
+                          .start_line = 1,
+                          .end_line = 1};
+    cbm_node_t file = {.project = project,
+                       .label = "File",
+                       .name = "main.c",
+                       .qualified_name = "search-folder-scope.src.main.c",
+                       .file_path = "src/main.c"};
+    cbm_node_t symbol = {.project = project,
+                         .label = "Variable",
+                         .name = "FOLDER_SCOPE_NEEDLE",
+                         .qualified_name = "search-folder-scope.src.FOLDER_SCOPE_NEEDLE",
+                         .file_path = "src/main.c",
+                         .start_line = 1,
+                         .end_line = 1};
+    ASSERT_GT(cbm_store_upsert_node(store, &folder), 0);
+    ASSERT_GT(cbm_store_upsert_node(store, &builtin), 0);
+    ASSERT_GT(cbm_store_upsert_node(store, &file), 0);
+    ASSERT_GT(cbm_store_upsert_node(store, &symbol), 0);
 
-    cbm_store_t *st = cbm_mcp_server_store(srv);
-    ASSERT_NOT_NULL(st);
+    char *response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"FOLDER_SCOPE_NEEDLE\",\"project\":\"search-folder-scope\","
+        "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    ASSERT_NULL(strstr(response, "\"isError\":true"));
+    ASSERT_NOT_NULL(strstr(response, "search-folder-scope.src.FOLDER_SCOPE_NEEDLE"));
 
-    const char *proj = "arch-path";
-    cbm_mcp_server_set_project(srv, proj);
-    cbm_store_upsert_project(st, proj, "/tmp/arch-path");
+    free(response);
+    cbm_mcp_server_free(srv);
+    cbm_unlink(source_path);
+    cbm_rmdir(source_dir);
+    cbm_rmdir(tmp);
+    PASS();
+}
 
-    cbm_node_t pkg_global = {.project = proj,
-                             .label = "Package",
-                             .name = "Django",
-                             .qualified_name = "arch-path.Django",
-                             .file_path = "vendor/django/__init__.py"};
-    cbm_store_upsert_node(st, &pkg_global);
+TEST(search_code_scoped_file_pattern_is_busybox_portable) {
+#ifdef _WIN32
+    SKIP_PLATFORM("POSIX BusyBox-compatible grep contract");
+#else
+    char tmp[CBM_SZ_512];
+    snprintf(tmp, sizeof(tmp), "%s/cbm-search-busybox-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
 
-    cbm_node_t pkg_local = {.project = proj,
-                            .label = "Package",
-                            .name = "hoa",
-                            .qualified_name = "arch-path.hoa",
-                            .file_path = "apps/hoa/main.go"};
-    cbm_store_upsert_node(st, &pkg_local);
+    char bin_dir[CBM_SZ_1K];
+    char fake_grep[CBM_SZ_1K];
+    char source_path[CBM_SZ_1K];
+    snprintf(bin_dir, sizeof(bin_dir), "%s/bin", tmp);
+    snprintf(fake_grep, sizeof(fake_grep), "%s/grep", bin_dir);
+    snprintf(source_path, sizeof(source_path), "%s/R&D-main.c", tmp);
+    ASSERT_EQ(cbm_mkdir(bin_dir), 0);
+    ASSERT_EQ(th_write_file(fake_grep,
+                            "#!/bin/sh\n"
+                            "for arg in \"$@\"; do\n"
+                            "  case \"$arg\" in --include*) exit 97 ;; esac\n"
+                            "done\n"
+                            "if [ -x /usr/bin/grep ]; then exec /usr/bin/grep \"$@\"; fi\n"
+                            "exec /bin/grep \"$@\"\n"),
+              0);
+    ASSERT_EQ(chmod(fake_grep, 0700), 0);
+    ASSERT_EQ(th_write_file(source_path, "int BUSYBOX_GREP_NEEDLE = 1;\n"), 0);
 
-    cbm_node_t f_hoa = {.project = proj,
-                        .label = "File",
-                        .name = "main.go",
-                        .qualified_name = "arch-path.apps.hoa.main.go",
-                        .file_path = "apps/hoa/main.go"};
-    cbm_store_upsert_node(st, &f_hoa);
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-busybox";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    cbm_node_t file = {.project = project,
+                       .label = "File",
+                       .name = "R&D-main.c",
+                       .qualified_name = "search-busybox.R&D-main.c",
+                       .file_path = "R&D-main.c"};
+    cbm_node_t symbol = {.project = project,
+                         .label = "Variable",
+                         .name = "BUSYBOX_GREP_NEEDLE",
+                         .qualified_name = "search-busybox.BUSYBOX_GREP_NEEDLE",
+                         .file_path = "R&D-main.c",
+                         .start_line = 1,
+                         .end_line = 1};
+    ASSERT_GT(cbm_store_upsert_node(store, &file), 0);
+    ASSERT_GT(cbm_store_upsert_node(store, &symbol), 0);
+
+    mcp_test_env_backup_t path_backup = {.name = "PATH"};
+    const char *path = getenv(path_backup.name);
+    path_backup.present = path != NULL;
+    path_backup.value = path ? strdup(path) : NULL;
+    ASSERT_TRUE(!path || path_backup.value != NULL);
+    char forced_path[CBM_SZ_2K];
+    int forced_length = snprintf(forced_path, sizeof(forced_path), "%s:/usr/bin:/bin", bin_dir);
+    ASSERT_TRUE(forced_length > 0 && (size_t)forced_length < sizeof(forced_path));
+    ASSERT_EQ(cbm_setenv("PATH", forced_path, 1), 0);
 
-    cbm_node_t f_other = {.project = proj,
-                          .label = "File",
-                          .name = "other.go",
-                          .qualified_name = "arch-path.other.go",
-                          .file_path = "lib/other.go"};
-    cbm_store_upsert_node(st, &f_other);
+    char *response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"BUSYBOX_GREP_NEEDLE\",\"project\":\"search-busybox\","
+        "\"file_pattern\":\"*R&D*.c\",\"format\":\"json\"}");
+    mcp_test_restore_env(&path_backup, 1U);
+    char *inner = extract_text_content(response);
+    bool portable_success = response && !strstr(response, "\"isError\":true") && inner &&
+                            strstr(inner, "\"total_grep_matches\":1") &&
+                            strstr(inner, "search-busybox.BUSYBOX_GREP_NEEDLE");
 
-    char *resp_root = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":92,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"get_architecture\","
-             "\"arguments\":{\"project\":\"arch-path\",\"aspects\":[\"packages\"]}}}");
-    ASSERT_NOT_NULL(resp_root);
-    char *inner_root = extract_text_content(resp_root);
-    ASSERT_NOT_NULL(inner_root);
-    ASSERT_NOT_NULL(strstr(inner_root, "Django"));
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    cbm_unlink(source_path);
+    cbm_unlink(fake_grep);
+    cbm_rmdir(bin_dir);
+    cbm_rmdir(tmp);
+    ASSERT_TRUE(portable_success);
+    PASS();
+#endif
+}
 
-    char *resp_scoped =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":93,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"get_architecture\","
-                                   "\"arguments\":{\"project\":\"arch-path\",\"path\":\"apps/hoa\","
-                                   "\"aspects\":[\"packages\"]}}}");
-    ASSERT_NOT_NULL(resp_scoped);
-    char *inner_scoped = extract_text_content(resp_scoped);
-    ASSERT_NOT_NULL(inner_scoped);
+TEST(search_code_recursive_fallback_propagates_discovery_failures) {
+#ifdef _WIN32
+    SKIP_PLATFORM("POSIX find/sort/xargs fallback contract");
+#else
+    char tmp[CBM_SZ_512];
+    snprintf(tmp, sizeof(tmp), "%s/cbm-search-find-status-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
 
-    ASSERT_NOT_NULL(strstr(inner_scoped, "root_total_nodes"));
-    ASSERT_NOT_NULL(strstr(inner_scoped, "scoped_total_nodes"));
-    ASSERT_NOT_NULL(strstr(inner_scoped, "path: "));
-    ASSERT_NOT_NULL(strstr(inner_scoped, "hoa"));
-    ASSERT_NULL(strstr(inner_scoped, "Django"));
+    char bin_dir[CBM_SZ_1K];
+    char sort_bin_dir[CBM_SZ_1K];
+    char fake_find[CBM_SZ_1K];
+    char fake_sort[CBM_SZ_1K];
+    char victim[CBM_SZ_1K];
+    snprintf(bin_dir, sizeof(bin_dir), "%s/bin", tmp);
+    snprintf(sort_bin_dir, sizeof(sort_bin_dir), "%s/sort-bin", tmp);
+    snprintf(fake_find, sizeof(fake_find), "%s/find", bin_dir);
+    snprintf(fake_sort, sizeof(fake_sort), "%s/sort", sort_bin_dir);
+    snprintf(victim, sizeof(victim), "%s/victim.c", tmp);
+    ASSERT_EQ(cbm_mkdir(bin_dir), 0);
+    ASSERT_EQ(cbm_mkdir(sort_bin_dir), 0);
+    ASSERT_EQ(th_write_file(fake_find, "#!/bin/sh\n"
+                                       "printf '%s\\000' \"$1/victim.c\"\n"
+                                       "exit 73\n"),
+              0);
+    ASSERT_EQ(chmod(fake_find, 0700), 0);
+    ASSERT_EQ(th_write_file(fake_sort, "#!/bin/sh\nexit 74\n"), 0);
+    ASSERT_EQ(chmod(fake_sort, 0700), 0);
+    ASSERT_EQ(th_write_file(victim, "int FALLBACK_STATUS_NEEDLE = 1;\n"), 0);
 
-    int root_nodes = 0;
-    int scoped_nodes = 0;
-    /* TOON scalar form (`key: N`) with JSON fallback for format:"json". */
-    const char *rt = strstr(inner_scoped, "root_total_nodes: ");
-    const char *stn = strstr(inner_scoped, "scoped_total_nodes: ");
-    if (rt) {
-        sscanf(rt, "root_total_nodes: %d", &root_nodes);
-    } else if ((rt = strstr(inner_scoped, "\"root_total_nodes\":")) != NULL) {
-        sscanf(rt, "\"root_total_nodes\":%d", &root_nodes);
-    }
-    if (stn) {
-        sscanf(stn, "scoped_total_nodes: %d", &scoped_nodes);
-    } else if ((stn = strstr(inner_scoped, "\"scoped_total_nodes\":")) != NULL) {
-        sscanf(stn, "\"scoped_total_nodes\":%d", &scoped_nodes);
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-find-status";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+
+    mcp_test_env_backup_t path_backup = {.name = "PATH"};
+    const char *path = getenv(path_backup.name);
+    path_backup.present = path != NULL;
+    path_backup.value = path ? strdup(path) : NULL;
+    ASSERT_TRUE(!path || path_backup.value != NULL);
+    char forced_path[CBM_SZ_2K];
+    int forced_length = snprintf(forced_path, sizeof(forced_path), "%s:/usr/bin:/bin", bin_dir);
+    ASSERT_TRUE(forced_length > 0 && (size_t)forced_length < sizeof(forced_path));
+    ASSERT_EQ(cbm_setenv("PATH", forced_path, 1), 0);
+
+    char *failed_response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"FALLBACK_STATUS_NEEDLE\",\"project\":\"search-find-status\","
+        "\"file_pattern\":\"*.c\",\"format\":\"json\"}");
+    bool discovery_failure_propagated = failed_response &&
+                                        strstr(failed_response, "\"isError\":true") &&
+                                        strstr(failed_response, "complete result set was scanned");
+    free(failed_response);
+
+    int forced_sort_length =
+        snprintf(forced_path, sizeof(forced_path), "%s:/usr/bin:/bin", sort_bin_dir);
+    ASSERT_TRUE(forced_sort_length > 0 && (size_t)forced_sort_length < sizeof(forced_path));
+    ASSERT_EQ(cbm_setenv("PATH", forced_path, 1), 0);
+    char *sort_failed_response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"FALLBACK_STATUS_NEEDLE\",\"project\":\"search-find-status\","
+        "\"file_pattern\":\"*.c\",\"format\":\"json\"}");
+    bool sort_failure_propagated = sort_failed_response &&
+                                   strstr(sort_failed_response, "\"isError\":true") &&
+                                   strstr(sort_failed_response, "complete result set was scanned");
+    free(sort_failed_response);
+    mcp_test_restore_env(&path_backup, 1U);
+
+    char *no_match_response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"ABSENT_FALLBACK_NEEDLE\",\"project\":\"search-find-status\","
+        "\"file_pattern\":\"*.c\",\"format\":\"json\"}");
+    char *no_match_inner = extract_text_content(no_match_response);
+    bool no_match_is_exact_success =
+        no_match_response && !strstr(no_match_response, "\"isError\":true") && no_match_inner &&
+        strstr(no_match_inner, "\"total_grep_matches\":0") &&
+        strstr(no_match_inner, "\"total_relation\":\"eq\"");
+    free(no_match_inner);
+    free(no_match_response);
+
+    ASSERT_EQ(cbm_unlink(victim), 0);
+    char *empty_response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"ABSENT_FALLBACK_NEEDLE\",\"project\":\"search-find-status\","
+        "\"file_pattern\":\"*.c\",\"format\":\"json\"}");
+    char *empty_inner = extract_text_content(empty_response);
+    bool empty_discovery_is_exact_success =
+        empty_response && !strstr(empty_response, "\"isError\":true") && empty_inner &&
+        strstr(empty_inner, "\"total_grep_matches\":0") &&
+        strstr(empty_inner, "\"total_relation\":\"eq\"");
+    free(empty_inner);
+    free(empty_response);
+
+    cbm_mcp_server_free(srv);
+    ASSERT_EQ(th_rmtree(tmp), 0);
+    ASSERT_TRUE(discovery_failure_propagated);
+    ASSERT_TRUE(sort_failure_propagated);
+    ASSERT_TRUE(no_match_is_exact_success);
+    ASSERT_TRUE(empty_discovery_is_exact_success);
+    PASS();
+#endif
+}
+
+TEST(search_code_default_budget_limits_raw_rows_before_graph_results) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_srch_budget_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    char src_path[512];
+    snprintf(src_path, sizeof(src_path), "%s/raw.txt", tmp);
+    FILE *fp = cbm_fopen(src_path, "wb");
+    ASSERT_NOT_NULL(fp);
+    for (int row = 0; row < 20; row++) {
+        fprintf(fp, "RAW_NEEDLE_%02d_", row);
+        for (int col = 0; col < 850; col++) {
+            fputc('a' + row % 26, fp);
+        }
+        fputc('\n', fp);
     }
-    ASSERT_TRUE(root_nodes > scoped_nodes);
-    ASSERT_TRUE(scoped_nodes > 0);
+    fclose(fp);
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "search-budget";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"RAW_NEEDLE\",\"project\":\"search-budget\","
+                            "\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_TRUE(strlen(inner) <= 3200U * 4U);
+    ASSERT_NOT_NULL(strstr(inner, "\"raw_match_count\":20"));
+    ASSERT_NOT_NULL(strstr(inner, "\"raw_returned\":5"));
+    ASSERT_NOT_NULL(strstr(inner, "\"raw_has_more\":true"));
+    free(inner);
+    free(response);
+
+    response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"RAW_NEEDLE\",\"project\":\"search-budget\","
+                            "\"raw_limit\":20,\"max_output_tokens\":20000,\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"raw_returned\":20"));
+    ASSERT_NOT_NULL(strstr(inner, "\"raw_has_more\":false"));
+    free(inner);
+    free(response);
 
-    free(inner_scoped);
-    free(resp_scoped);
-    free(inner_root);
-    free(resp_root);
     cbm_mcp_server_free(srv);
+    cbm_unlink(src_path);
+    cbm_rmdir(tmp);
     PASS();
 }
 
-TEST(tool_query_graph_missing_query) {
-    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+TEST(search_code_raw_and_directory_remainders_are_independently_pageable) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "%s/cbm_srch_section_pages_XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
 
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":23,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"query_graph\","
-                                   "\"arguments\":{}}}");
-    ASSERT_NOT_NULL(resp);
-    /* Should return error about missing query */
-    ASSERT_NOT_NULL(strstr(resp, "required"));
-    free(resp);
+    const char *directories[] = {"graph-a", "graph-b"};
+    for (size_t i = 0; i < sizeof(directories) / sizeof(directories[0]); i++) {
+        char path[CBM_SZ_4K];
+        snprintf(path, sizeof(path), "%s/%s", tmp, directories[i]);
+        ASSERT_EQ(cbm_mkdir(path), 0);
+    }
+
+    const char *relative_paths[] = {"graph-a/route.c", "graph-b/function.c", "raw-a.txt",
+                                    "raw-b.txt"};
+    for (size_t i = 0; i < sizeof(relative_paths) / sizeof(relative_paths[0]); i++) {
+        char path[CBM_SZ_4K];
+        snprintf(path, sizeof(path), "%s/%s", tmp, relative_paths[i]);
+        ASSERT_EQ(th_write_file(path, i < 2 ? "int PAGE_NEEDLE_graph = 1;\n"
+                                            : "int PAGE_NEEDLE_raw = 1;\nint sentinel = 0;\n"),
+                  0);
+    }
 
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-section-pages";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+
+    char route_qn[1200];
+    char function_qn[1200];
+    memset(route_qn, 'r', sizeof(route_qn) - 1U);
+    memset(function_qn, 'f', sizeof(function_qn) - 1U);
+    route_qn[sizeof(route_qn) - 1U] = '\0';
+    function_qn[sizeof(function_qn) - 1U] = '\0';
+    cbm_node_t nodes[] = {
+        {.project = project,
+         .label = "Route",
+         .name = "route_hit",
+         .qualified_name = route_qn,
+         .file_path = "graph-a/route.c",
+         .start_line = 1,
+         .end_line = 1},
+        {.project = project,
+         .label = "Function",
+         .name = "function_hit",
+         .qualified_name = function_qn,
+         .file_path = "graph-b/function.c",
+         .start_line = 1,
+         .end_line = 1},
+        /* These nodes put the files in the scoped grep list, but deliberately
+         * do not cover the matching first line, leaving one raw row per file. */
+        {.project = project,
+         .label = "Variable",
+         .name = "raw_a_sentinel",
+         .qualified_name = "fixture.raw_a_sentinel",
+         .file_path = "raw-a.txt",
+         .start_line = 2,
+         .end_line = 2},
+        {.project = project,
+         .label = "Variable",
+         .name = "raw_b_sentinel",
+         .qualified_name = "fixture.raw_b_sentinel",
+         .file_path = "raw-b.txt",
+         .start_line = 2,
+         .end_line = 2},
+    };
+    for (size_t i = 0; i < sizeof(nodes) / sizeof(nodes[0]); i++) {
+        ASSERT_GT(cbm_store_upsert_node(store, &nodes[i]), 0);
+    }
+
+    char *first_response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"PAGE_NEEDLE\",\"project\":\"search-section-pages\","
+                            "\"limit\":2,\"raw_limit\":1,\"directory_limit\":1,"
+                            "\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *first_inner = extract_text_content(first_response);
+    yyjson_doc *first_doc = first_inner ? yyjson_read(first_inner, strlen(first_inner), 0) : NULL;
+    yyjson_val *first_root = first_doc ? yyjson_doc_get_root(first_doc) : NULL;
+    yyjson_val *first_raw = first_root ? yyjson_obj_get(first_root, "raw_matches") : NULL;
+    yyjson_val *first_raw_rows = first_raw ? yyjson_obj_get(first_raw, "rows") : NULL;
+    yyjson_val *first_raw_row = first_raw_rows ? yyjson_arr_get(first_raw_rows, 0) : NULL;
+    yyjson_val *first_directories = first_root ? yyjson_obj_get(first_root, "directories") : NULL;
+    bool first_page_bound =
+        first_root && yyjson_get_int(yyjson_obj_get(first_root, "raw_next_offset")) == 1 &&
+        yyjson_get_int(yyjson_obj_get(first_root, "directory_next_offset")) == 1 && first_raw_row &&
+        strcmp(yyjson_get_str(yyjson_arr_get(first_raw_row, 0)), "raw-a.txt") == 0 &&
+        yyjson_obj_get(first_directories, "graph-a/") != NULL &&
+        yyjson_obj_get(first_directories, "graph-b/") == NULL;
+
+    char *second_response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"PAGE_NEEDLE\",\"project\":\"search-section-pages\","
+                            "\"limit\":2,\"raw_limit\":1,\"raw_offset\":1,"
+                            "\"directory_limit\":1,\"directory_offset\":1,"
+                            "\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *second_inner = extract_text_content(second_response);
+    yyjson_doc *second_doc =
+        second_inner ? yyjson_read(second_inner, strlen(second_inner), 0) : NULL;
+    yyjson_val *second_root = second_doc ? yyjson_doc_get_root(second_doc) : NULL;
+    yyjson_val *second_raw = second_root ? yyjson_obj_get(second_root, "raw_matches") : NULL;
+    yyjson_val *second_raw_rows = second_raw ? yyjson_obj_get(second_raw, "rows") : NULL;
+    yyjson_val *second_raw_row = second_raw_rows ? yyjson_arr_get(second_raw_rows, 0) : NULL;
+    yyjson_val *second_directories =
+        second_root ? yyjson_obj_get(second_root, "directories") : NULL;
+    bool remainders_reachable =
+        second_root && second_raw_row &&
+        strcmp(yyjson_get_str(yyjson_arr_get(second_raw_row, 0)), "raw-b.txt") == 0 &&
+        yyjson_obj_get(second_directories, "graph-a/") == NULL &&
+        yyjson_obj_get(second_directories, "graph-b/") != NULL &&
+        !yyjson_get_bool(yyjson_obj_get(second_root, "raw_has_more")) &&
+        !yyjson_get_bool(yyjson_obj_get(second_root, "directories_has_more"));
+
+    char *floor_response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"PAGE_NEEDLE\",\"project\":\"search-section-pages\","
+                            "\"result_limit\":1,\"raw_limit\":1,\"directory_limit\":1,"
+                            "\"max_output_tokens\":128,\"format\":\"json\"}");
+    char *floor_inner = extract_text_content(floor_response);
+    yyjson_doc *floor_doc = floor_inner ? yyjson_read(floor_inner, strlen(floor_inner), 0) : NULL;
+    yyjson_val *floor_root = floor_doc ? yyjson_doc_get_root(floor_doc) : NULL;
+    bool json_floor_is_bounded_and_resumable =
+        floor_root && strlen(floor_inner) <= 128U * 4U &&
+        yyjson_get_int(yyjson_obj_get(floor_root, "total_results")) == 2 &&
+        yyjson_get_int(yyjson_obj_get(floor_root, "raw_match_count")) == 2 &&
+        yyjson_get_int(yyjson_obj_get(floor_root, "directories_total")) == 2 &&
+        yyjson_get_int(yyjson_obj_get(floor_root, "results_returned")) == 0 &&
+        yyjson_get_int(yyjson_obj_get(floor_root, "raw_returned")) == 0 &&
+        yyjson_get_int(yyjson_obj_get(floor_root, "directories_returned")) == 0 &&
+        yyjson_get_bool(yyjson_obj_get(floor_root, "has_more")) &&
+        yyjson_get_bool(yyjson_obj_get(floor_root, "raw_has_more")) &&
+        yyjson_get_bool(yyjson_obj_get(floor_root, "directories_has_more"));
+    yyjson_doc_free(floor_doc);
+    free(floor_inner);
+    free(floor_response);
+
+    floor_response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"PAGE_NEEDLE\",\"project\":\"search-section-pages\","
+                            "\"result_limit\":1,\"raw_limit\":1,\"directory_limit\":1,"
+                            "\"max_output_tokens\":128}");
+    floor_inner = extract_text_content(floor_response);
+    bool compact_floor_is_bounded_and_resumable =
+        floor_inner && strlen(floor_inner) <= 128U * 4U &&
+        strstr(floor_inner, "results_returned: 0") && strstr(floor_inner, "has_more: true") &&
+        strstr(floor_inner, "raw_returned: 0") && strstr(floor_inner, "raw_has_more: true") &&
+        strstr(floor_inner, "directories_returned: 0") &&
+        strstr(floor_inner, "directories_has_more: true");
+    free(floor_inner);
+    free(floor_response);
+
+    yyjson_doc_free(second_doc);
+    free(second_inner);
+    free(second_response);
+    yyjson_doc_free(first_doc);
+    free(first_inner);
+    free(first_response);
     cbm_mcp_server_free(srv);
+    ASSERT_EQ(th_rmtree(tmp), 0);
+
+    ASSERT_TRUE(first_page_bound);
+    ASSERT_TRUE(remainders_reachable);
+    ASSERT_TRUE(json_floor_is_bounded_and_resumable);
+    ASSERT_TRUE(compact_floor_is_bounded_and_resumable);
     PASS();
 }
 
-/* ══════════════════════════════════════════════════════════════════
- *  PIPELINE-DEPENDENT TOOL HANDLERS
- * ══════════════════════════════════════════════════════════════════ */
+TEST(search_code_ranked_results_have_lossless_second_page) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "%s/cbm_srch_result_pages_XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+
+    const char *relative_paths[] = {"alpha.c", "beta.c", "gamma.c"};
+    const char *qualified_names[] = {"fixture.alpha", "fixture.beta", "fixture.gamma"};
+    for (size_t i = 0; i < sizeof(relative_paths) / sizeof(relative_paths[0]); i++) {
+        char path[CBM_SZ_4K];
+        snprintf(path, sizeof(path), "%s/%s", tmp, relative_paths[i]);
+        ASSERT_EQ(th_write_file(path, "int RESULT_PAGE_NEEDLE = 1;\n"), 0);
+    }
 
-TEST(tool_index_repository_missing_path) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-result-pages";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    for (size_t i = 0; i < sizeof(relative_paths) / sizeof(relative_paths[0]); i++) {
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = qualified_names[i],
+                           .qualified_name = qualified_names[i],
+                           .file_path = relative_paths[i],
+                           .start_line = 1,
+                           .end_line = 1};
+        ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    }
+
+    const char *page_args =
+        "{\"pattern\":\"RESULT_PAGE_NEEDLE\",\"project\":\"search-result-pages\","
+        "\"result_limit\":1,\"result_offset\":1,\"raw_limit\":0,\"directory_limit\":0,"
+        "\"max_output_tokens\":10000,\"format\":\"json\"}";
+    char *response = cbm_mcp_handle_tool(srv, "search_code", page_args);
+    char *inner = extract_text_content(response);
+    yyjson_doc *doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *rows = root ? yyjson_obj_get(root, "rows") : NULL;
+    yyjson_val *row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    bool json_page_is_exact =
+        root && row && yyjson_arr_size(rows) == 1 &&
+        strcmp(yyjson_get_str(yyjson_arr_get(row, 0)), "fixture.beta") == 0 &&
+        yyjson_get_int(yyjson_obj_get(root, "total_results")) == 3 &&
+        strcmp(yyjson_get_str(yyjson_obj_get(root, "total_relation")), "eq") == 0 &&
+        yyjson_get_int(yyjson_obj_get(root, "results_returned")) == 1 &&
+        yyjson_get_bool(yyjson_obj_get(root, "has_more")) &&
+        yyjson_get_int(yyjson_obj_get(root, "next_offset")) == 2;
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
 
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":30,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"index_repository\","
-                                   "\"arguments\":{}}}");
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "required"));
-    free(resp);
+    response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"RESULT_PAGE_NEEDLE\",\"project\":\"search-result-pages\","
+        "\"result_limit\":1,\"result_offset\":1,\"raw_limit\":0,\"directory_limit\":0,"
+        "\"max_output_tokens\":10000}");
+    inner = extract_text_content(response);
+    bool compact_page_is_exact =
+        inner && strstr(inner, "fixture.beta") && !strstr(inner, "fixture.alpha") &&
+        !strstr(inner, "fixture.gamma") && strstr(inner, "total_results: 3") &&
+        strstr(inner, "total_relation: eq") && strstr(inner, "results_returned: 1") &&
+        strstr(inner, "has_more: true") && strstr(inner, "next_offset: 2");
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"RESULT_PAGE_NEEDLE\",\"project\":\"search-result-pages\","
+        "\"result_limit\":1,\"result_offset\":2,\"raw_limit\":0,\"directory_limit\":0,"
+        "\"max_output_tokens\":10000,\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    root = doc ? yyjson_doc_get_root(doc) : NULL;
+    rows = root ? yyjson_obj_get(root, "rows") : NULL;
+    row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    bool final_page_terminates =
+        root && row && strcmp(yyjson_get_str(yyjson_arr_get(row, 0)), "fixture.gamma") == 0 &&
+        !yyjson_get_bool(yyjson_obj_get(root, "has_more")) &&
+        yyjson_obj_get(root, "next_offset") == NULL;
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
 
     cbm_mcp_server_free(srv);
+    ASSERT_EQ(th_rmtree(tmp), 0);
+    ASSERT_TRUE(json_page_is_exact);
+    ASSERT_TRUE(compact_page_is_exact);
+    ASSERT_TRUE(final_page_terminates);
     PASS();
 }
 
-TEST(tool_get_code_snippet_missing_qn) {
+static char *search_code_long_identity(char fill, bool path) {
+    enum { LONG_IDENTITY_LENGTH = 2304, FIRST_DIRECTORY_LENGTH = 200 };
+    char *value = malloc(LONG_IDENTITY_LENGTH + 1U);
+    if (!value) {
+        return NULL;
+    }
+    memset(value, fill, LONG_IDENTITY_LENGTH);
+    if (path) {
+        for (size_t i = FIRST_DIRECTORY_LENGTH; i + 16U < LONG_IDENTITY_LENGTH; i += 73U) {
+            value[i] = '/';
+        }
+        static const char suffix[] = "/needle.c";
+        memcpy(value + LONG_IDENTITY_LENGTH - (sizeof(suffix) - 1U), suffix, sizeof(suffix) - 1U);
+    } else {
+        for (size_t i = 61U; i + 16U < LONG_IDENTITY_LENGTH; i += 61U) {
+            value[i] = '.';
+        }
+        static const char suffix[] = ".Needle";
+        memcpy(value + LONG_IDENTITY_LENGTH - (sizeof(suffix) - 1U), suffix, sizeof(suffix) - 1U);
+    }
+    value[LONG_IDENTITY_LENGTH] = '\0';
+    return value;
+}
+
+TEST(search_code_ranked_budget_omission_has_lossless_continuation) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "%s/cbm_srch_result_budget_XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    const char *paths[] = {"one.c", "two.c", "three.c"};
+    char *qualified_names[] = {search_code_long_identity('x', false),
+                               search_code_long_identity('y', false),
+                               search_code_long_identity('z', false)};
+    ASSERT_NOT_NULL(qualified_names[0]);
+    ASSERT_NOT_NULL(qualified_names[1]);
+    ASSERT_NOT_NULL(qualified_names[2]);
+
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-result-budget";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    for (size_t i = 0; i < sizeof(paths) / sizeof(paths[0]); i++) {
+        char path[CBM_SZ_4K];
+        snprintf(path, sizeof(path), "%s/%s", tmp, paths[i]);
+        ASSERT_EQ(th_write_file(path, "int RESULT_BUDGET_NEEDLE = 1;\n"), 0);
+        cbm_node_t node = {.project = project,
+                           .label = "Function",
+                           .name = "budget_hit",
+                           .qualified_name = qualified_names[i],
+                           .file_path = paths[i],
+                           .start_line = 1,
+                           .end_line = 1};
+        ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    }
 
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":31,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"get_code_snippet\","
-                                   "\"arguments\":{}}}");
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "required"));
-    free(resp);
+    char *response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"RESULT_BUDGET_NEEDLE\",\"project\":\"search-result-budget\","
+        "\"result_limit\":3,\"result_offset\":0,\"raw_limit\":0,\"directory_limit\":0,"
+        "\"max_output_tokens\":800,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    yyjson_doc *doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *rows = root ? yyjson_obj_get(root, "rows") : NULL;
+    yyjson_val *row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    bool first_page_advances =
+        root && row && yyjson_arr_size(rows) == 1 &&
+        strcmp(yyjson_get_str(yyjson_arr_get(row, 0)), qualified_names[0]) == 0 &&
+        yyjson_get_int(yyjson_obj_get(root, "total_results")) == 3 &&
+        yyjson_get_int(yyjson_obj_get(root, "results_returned")) == 1 &&
+        yyjson_get_bool(yyjson_obj_get(root, "has_more")) &&
+        yyjson_get_int(yyjson_obj_get(root, "next_offset")) == 1 &&
+        strcmp(yyjson_get_str(yyjson_obj_get(root, "truncation_reason")), "output_budget") == 0;
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"RESULT_BUDGET_NEEDLE\",\"project\":\"search-result-budget\","
+        "\"result_limit\":3,\"result_offset\":1,\"raw_limit\":0,\"directory_limit\":0,"
+        "\"max_output_tokens\":800,\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    root = doc ? yyjson_doc_get_root(doc) : NULL;
+    rows = root ? yyjson_obj_get(root, "rows") : NULL;
+    row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    bool second_page_advances =
+        root && row && yyjson_arr_size(rows) == 1 &&
+        strcmp(yyjson_get_str(yyjson_arr_get(row, 0)), qualified_names[1]) == 0 &&
+        yyjson_get_int(yyjson_obj_get(root, "next_offset")) == 2;
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"RESULT_BUDGET_NEEDLE\",\"project\":\"search-result-budget\","
+        "\"result_limit\":1,\"result_offset\":0,\"raw_limit\":0,\"directory_limit\":0,"
+        "\"max_output_tokens\":128,\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    root = doc ? yyjson_doc_get_root(doc) : NULL;
+    bool floor_is_truthful =
+        root && inner && strlen(inner) <= 128U * 4U &&
+        yyjson_get_int(yyjson_obj_get(root, "total_results")) == 3 &&
+        yyjson_get_int(yyjson_obj_get(root, "results_returned")) == 0 &&
+        yyjson_get_bool(yyjson_obj_get(root, "has_more")) &&
+        yyjson_obj_get(root, "next_offset") == NULL &&
+        yyjson_get_bool(yyjson_obj_get(root, "result_continuation_requires_higher_budget"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
 
     cbm_mcp_server_free(srv);
+    ASSERT_EQ(th_rmtree(tmp), 0);
+    for (size_t i = 0; i < sizeof(qualified_names) / sizeof(qualified_names[0]); i++) {
+        free(qualified_names[i]);
+    }
+    ASSERT_TRUE(first_page_advances);
+    ASSERT_TRUE(second_page_advances);
+    ASSERT_TRUE(floor_is_truthful);
     PASS();
 }
 
-TEST(tool_get_code_snippet_not_found) {
-    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":32,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"get_code_snippet\","
-                                   "\"arguments\":{\"qualified_name\":\"nonexistent.func\","
-                                   "\"project\":\"nonexistent\"}}}");
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "not found"));
-    free(resp);
-
-    cbm_mcp_server_free(srv);
+TEST(search_code_preserves_multi_kib_identities_and_distinct_long_directories) {
+    char *qualified_names[] = {search_code_long_identity('x', false),
+                               search_code_long_identity('y', false)};
+    char *file_paths[] = {search_code_long_identity('a', true),
+                          search_code_long_identity('z', true)};
+    ASSERT_NOT_NULL(qualified_names[0]);
+    ASSERT_NOT_NULL(qualified_names[1]);
+    ASSERT_NOT_NULL(file_paths[0]);
+    ASSERT_NOT_NULL(file_paths[1]);
+
+    const char *qualified_name_view[] = {qualified_names[0], qualified_names[1]};
+    const char *file_path_view[] = {file_paths[0], file_paths[1]};
+    char *tree =
+        cbm_mcp_render_search_rows_for_testing(qualified_name_view, file_path_view, 2, false);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NOT_NULL(strstr(tree, qualified_names[0]));
+    ASSERT_NOT_NULL(strstr(tree, qualified_names[1]));
+    ASSERT_NOT_NULL(strstr(tree, file_paths[0]));
+    ASSERT_NOT_NULL(strstr(tree, file_paths[1]));
+    ASSERT_NOT_NULL(strstr(tree, "directories_total: 2"));
+    free(tree);
+
+    char *json =
+        cbm_mcp_render_search_rows_for_testing(qualified_name_view, file_path_view, 2, true);
+    ASSERT_NOT_NULL(json);
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *rows = yyjson_obj_get(root, "rows");
+    ASSERT_EQ((int)yyjson_arr_size(rows), 2);
+    yyjson_val *first = yyjson_arr_get(rows, 0);
+    yyjson_val *second = yyjson_arr_get(rows, 1);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(first, 0)), qualified_names[0]);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(first, 2)), file_paths[0]);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(second, 0)), qualified_names[1]);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(second, 2)), file_paths[1]);
+
+    char *first_directory = cbm_strndup(file_paths[0], 201U);
+    char *second_directory = cbm_strndup(file_paths[1], 201U);
+    ASSERT_NOT_NULL(first_directory);
+    ASSERT_NOT_NULL(second_directory);
+    yyjson_val *directories = yyjson_obj_get(root, "directories");
+    ASSERT_EQ((int)yyjson_obj_size(directories), 2);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_obj_get(directories, first_directory)), 1);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_obj_get(directories, second_directory)), 1);
+
+    free(first_directory);
+    free(second_directory);
+    yyjson_doc_free(doc);
+    free(json);
+    free(qualified_names[0]);
+    free(qualified_names[1]);
+    free(file_paths[0]);
+    free(file_paths[1]);
     PASS();
 }
 
-TEST(tool_search_code_missing_pattern) {
+TEST(search_code_long_raw_line_is_one_truthfully_truncated_match) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_srch_long_line_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    char source_path[512];
+    snprintf(source_path, sizeof(source_path), "%s/long.txt", tmp);
+    FILE *source = cbm_fopen(source_path, "wb");
+    ASSERT_NOT_NULL(source);
+    fputs("LONG_RAW_NEEDLE_", source);
+    for (int i = 0; i < 2500; i++) {
+        fputc('q', source);
+    }
+    fputc('\n', source);
+    fclose(source);
+
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "search-long-raw-line";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
 
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":33,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"search_code\","
-                                   "\"arguments\":{}}}");
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "required"));
-    free(resp);
+    char *response =
+        cbm_mcp_handle_tool(srv, "search_code",
+                            "{\"pattern\":\"LONG_RAW_NEEDLE\",\"project\":\"search-long-raw-line\","
+                            "\"raw_limit\":5,\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_obj_get(root, "total_grep_matches")), 1);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_obj_get(root, "raw_match_count")), 1);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_obj_get(root, "raw_content_truncated")), 1);
+    yyjson_val *raw = yyjson_obj_get(root, "raw_matches");
+    yyjson_val *rows = yyjson_obj_get(raw, "rows");
+    ASSERT_EQ((int)yyjson_arr_size(rows), 1);
+    yyjson_val *row = yyjson_arr_get(rows, 0);
+    const char *content = yyjson_get_str(yyjson_arr_get(row, 2));
+    ASSERT_NOT_NULL(content);
+    ASSERT_NOT_NULL(strstr(content, "LONG_RAW_NEEDLE_"));
+    ASSERT_EQ((int)strlen(content), CBM_SZ_1K - 1);
 
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
     cbm_mcp_server_free(srv);
+    cbm_unlink(source_path);
+    cbm_rmdir(tmp);
     PASS();
 }
 
-/* #1511 (distilled from @lukiod's #1512): search_code echoed a negative limit
- * back as the result count — "results: -5" — which an agent reads as an answer,
- * not as a rejected argument. Both halves matter: the schema declares the bound
- * so well-behaved clients never send it, and the handler clamps because a
- * schema is a request to the client, never a guarantee to the server. */
-TEST(tool_search_code_negative_limit_is_not_echoed_issue1511) {
-    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":35,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"search_code\","
-                                   "\"arguments\":{\"pattern\":\"func main\","
-                                   "\"project\":\"nonexistent\",\"limit\":-5}}}");
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NULL(strstr(resp, "results: -5"));
-    free(resp);
-    cbm_mcp_server_free(srv);
-    PASS();
-}
+TEST(search_code_raw_preview_centers_late_match_and_pages_content_bytes) {
+    enum { PREFIX_GLYPHS = 467, PREFIX_BYTES = PREFIX_GLYPHS * 3, SUFFIX_BYTES = 1400 };
+    static const char needle[] = "LATE_RAW_NEEDLE";
+    static const char prefix_glyph[] = "\xE7\x95\x8C"; /* U+754C, three UTF-8 bytes */
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "%s/cbm_srch_late_raw_XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    char source_path[CBM_SZ_4K];
+    snprintf(source_path, sizeof(source_path), "%s/late.txt", tmp);
+    FILE *source = cbm_fopen(source_path, "wb");
+    ASSERT_NOT_NULL(source);
+    for (int i = 0; i < PREFIX_GLYPHS; i++) {
+        fputs(prefix_glyph, source);
+    }
+    fputs(needle, source);
+    for (int i = 0; i < SUFFIX_BYTES; i++) {
+        fputc('s', source);
+    }
+    fputs("\nsentinel\n", source);
+    fclose(source);
 
-TEST(tool_search_code_limit_declares_a_minimum_issue1511) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
-    char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":36,\"method\":\"tools/list\",\"params\":{}}");
-    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "search-late-raw";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    cbm_node_t sentinel = {.project = project,
+                           .label = "Variable",
+                           .name = "sentinel",
+                           .qualified_name = "fixture.sentinel",
+                           .file_path = "late.txt",
+                           .start_line = 2,
+                           .end_line = 2};
+    ASSERT_GT(cbm_store_upsert_node(store, &sentinel), 0);
 
-    yyjson_doc *doc = yyjson_read(resp, strlen(resp), 0);
+    char *response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"LATE_RAW_NEEDLE\",\"project\":\"search-late-raw\","
+        "\"result_limit\":1,\"raw_limit\":1,\"raw_offset\":0,\"directory_offset\":0,"
+        "\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    yyjson_doc *doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
     yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
-    yyjson_val *result = root ? yyjson_obj_get(root, "result") : NULL;
-    yyjson_val *tools = result ? yyjson_obj_get(result, "tools") : NULL;
-    yyjson_val *minimum = NULL;
-    if (tools && yyjson_is_arr(tools)) {
-        size_t index, max;
-        yyjson_val *tool;
-        yyjson_arr_foreach(tools, index, max, tool) {
-            yyjson_val *name = yyjson_obj_get(tool, "name");
-            if (!name || !yyjson_is_str(name) || strcmp(yyjson_get_str(name), "search_code") != 0) {
-                continue;
-            }
-            yyjson_val *schema = yyjson_obj_get(tool, "inputSchema");
-            yyjson_val *props = schema ? yyjson_obj_get(schema, "properties") : NULL;
-            yyjson_val *limit = props ? yyjson_obj_get(props, "limit") : NULL;
-            minimum = limit ? yyjson_obj_get(limit, "minimum") : NULL;
-            break;
-        }
-    }
-    bool declared = minimum && yyjson_is_int(minimum) && yyjson_get_int(minimum) >= 1;
+    yyjson_val *raw = root ? yyjson_obj_get(root, "raw_matches") : NULL;
+    yyjson_val *cols = raw ? yyjson_obj_get(raw, "cols") : NULL;
+    yyjson_val *rows = raw ? yyjson_obj_get(raw, "rows") : NULL;
+    yyjson_val *row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    const char *content = row ? yyjson_get_str(yyjson_arr_get(row, 2)) : NULL;
+    size_t content_start = row ? (size_t)yyjson_get_uint(yyjson_arr_get(row, 3)) : 0U;
+    size_t content_returned = row ? (size_t)yyjson_get_uint(yyjson_arr_get(row, 4)) : 0U;
+    size_t content_total = row ? (size_t)yyjson_get_uint(yyjson_arr_get(row, 5)) : 0U;
+    size_t match_start = row ? (size_t)yyjson_get_uint(yyjson_arr_get(row, 6)) : 0U;
+    size_t match_end = row ? (size_t)yyjson_get_uint(yyjson_arr_get(row, 7)) : 0U;
+    bool centered_preview =
+        cols && yyjson_arr_size(cols) >= 11 && row && content && strstr(content, needle) &&
+        content_start > 0 && content_returned == strlen(content) &&
+        content_returned <= CBM_SZ_1K - 1U &&
+        content_total == PREFIX_BYTES + strlen(needle) + SUFFIX_BYTES &&
+        match_start == PREFIX_BYTES && match_end == PREFIX_BYTES + strlen(needle) &&
+        content_start <= match_start && content_start + content_returned >= match_end &&
+        yyjson_get_bool(yyjson_arr_get(row, 8)) &&
+        yyjson_get_uint(yyjson_arr_get(row, 9)) > content_start &&
+        yyjson_get_bool(yyjson_arr_get(row, 10));
     yyjson_doc_free(doc);
-    free(resp);
-    cbm_mcp_server_free(srv);
+    free(inner);
+    free(response);
 
-    ASSERT_TRUE(declared);
+    response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"LATE_RAW_NEEDLE\",\"project\":\"search-late-raw\","
+        "\"result_limit\":1,\"raw_limit\":1,\"raw_offset\":0,\"raw_content_offset\":1,"
+        "\"directory_offset\":0,\"max_output_tokens\":10000,\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    root = doc ? yyjson_doc_get_root(doc) : NULL;
+    raw = root ? yyjson_obj_get(root, "raw_matches") : NULL;
+    rows = raw ? yyjson_obj_get(raw, "rows") : NULL;
+    row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    content = row ? yyjson_get_str(yyjson_arr_get(row, 2)) : NULL;
+    bool explicit_content_page = row && content && yyjson_get_uint(yyjson_arr_get(row, 3)) == 3 &&
+                                 strlen(content) == yyjson_get_uint(yyjson_arr_get(row, 4)) &&
+                                 !strstr(content, needle) &&
+                                 yyjson_get_uint(yyjson_arr_get(row, 5)) == content_total &&
+                                 yyjson_get_uint(yyjson_arr_get(row, 6)) == PREFIX_BYTES &&
+                                 yyjson_get_uint(yyjson_arr_get(row, 9)) == 3U + strlen(content) &&
+                                 yyjson_get_int(yyjson_obj_get(root, "raw_returned")) == 1;
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"LATE_RAW_NEEDLE\",\"project\":\"search-late-raw\","
+        "\"result_limit\":1,\"raw_limit\":1,\"raw_offset\":0,\"directory_offset\":0,"
+        "\"max_output_tokens\":10000}");
+    inner = extract_text_content(response);
+    bool compact_parity = inner && strstr(inner, needle) && strstr(inner, "content_start_byte") &&
+                          strstr(inner, "content_returned_bytes") &&
+                          strstr(inner, "content_total_bytes") &&
+                          strstr(inner, "match_start_byte") && strstr(inner, "match_end_byte");
+    free(inner);
+    free(response);
+
+    cbm_mcp_server_free(srv);
+    ASSERT_EQ(th_rmtree(tmp), 0);
+    ASSERT_TRUE(centered_preview);
+    ASSERT_TRUE(explicit_content_page);
+    ASSERT_TRUE(compact_parity);
     PASS();
 }
 
-TEST(tool_search_code_no_project) {
-    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+TEST(search_code_raw_preview_reversibly_pages_malformed_utf8_bytes) {
+    const char malformed[] = {'H', 'E', 'A', 'D', (char)0x80, (char)0xff, 'T', 'A', 'I', 'L', '\0'};
 
-    char *resp =
-        cbm_mcp_server_handle(srv, "{\"jsonrpc\":\"2.0\",\"id\":34,\"method\":\"tools/call\","
-                                   "\"params\":{\"name\":\"search_code\","
-                                   "\"arguments\":{\"pattern\":\"func main\","
-                                   "\"project\":\"nonexistent\"}}}");
-    ASSERT_NOT_NULL(resp);
-    /* No project indexed → error */
-    ASSERT_TRUE(strstr(resp, "not found") || strstr(resp, "not indexed") ||
-                strstr(resp, "required"));
-    free(resp);
+    char *json = cbm_mcp_render_raw_preview_for_testing(malformed, false, 0, true);
+    ASSERT_NOT_NULL(json);
+    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc); /* The direct JSON payload must remain strict JSON. */
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *raw = yyjson_obj_get(root, "raw_matches");
+    yyjson_val *rows = raw ? yyjson_obj_get(raw, "rows") : NULL;
+    yyjson_val *row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    ASSERT_NOT_NULL(row);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(row, 2)), "@bytes:4845414480ff5441494c");
+    ASSERT_EQ((int)yyjson_get_uint(yyjson_arr_get(row, 3)), 0);
+    ASSERT_EQ((int)yyjson_get_uint(yyjson_arr_get(row, 4)), 10);
+    ASSERT_EQ((int)yyjson_get_uint(yyjson_arr_get(row, 5)), 10);
+    yyjson_doc_free(doc);
+    free(json);
 
-    cbm_mcp_server_free(srv);
+    /* An explicit byte page beginning on malformed 0x80 must neither skip the
+     * byte nor reinterpret the offset as an encoded-text offset. */
+    json = cbm_mcp_render_raw_preview_for_testing(malformed, true, 4, true);
+    ASSERT_NOT_NULL(json);
+    doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    raw = yyjson_obj_get(root, "raw_matches");
+    rows = raw ? yyjson_obj_get(raw, "rows") : NULL;
+    row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    ASSERT_NOT_NULL(row);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(row, 2)), "@bytes:80ff5441494c");
+    ASSERT_EQ((int)yyjson_get_uint(yyjson_arr_get(row, 3)), 4);
+    ASSERT_EQ((int)yyjson_get_uint(yyjson_arr_get(row, 4)), 6);
+    ASSERT_EQ((int)yyjson_get_uint(yyjson_arr_get(row, 5)), 10);
+    yyjson_doc_free(doc);
+    free(json);
+
+    char *tree = cbm_mcp_render_raw_preview_for_testing(malformed, true, 4, false);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NOT_NULL(strstr(tree, "@bytes:80ff5441494c"));
+    ASSERT_NOT_NULL(strstr(tree, "content_start_byte"));
+    ASSERT_NOT_NULL(strstr(tree, " 4 6 10 "));
+    free(tree);
+
+    /* Literal reserved prefixes remain distinguishable from encoded bytes. */
+    json = cbm_mcp_render_raw_preview_for_testing("@bytes:literal", false, 0, true);
+    ASSERT_NOT_NULL(json);
+    doc = yyjson_read(json, strlen(json), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    raw = yyjson_obj_get(root, "raw_matches");
+    rows = raw ? yyjson_obj_get(raw, "rows") : NULL;
+    row = rows ? yyjson_arr_get(rows, 0) : NULL;
+    ASSERT_NOT_NULL(row);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_arr_get(row, 2)), "@utf8:@bytes:literal");
+    yyjson_doc_free(doc);
+    free(json);
+
+    tree = cbm_mcp_render_raw_preview_for_testing("@bytes:literal", false, 0, false);
+    ASSERT_NOT_NULL(tree);
+    ASSERT_NOT_NULL(strstr(tree, "@utf8:@bytes:literal"));
+    free(tree);
     PASS();
 }
 
-TEST(search_code_multi_word) {
-    char tmp[512];
-    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+TEST(search_code_match_locations_are_explicitly_bounded_and_expandable) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_srch_match_locations_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    char source_path[512];
+    snprintf(source_path, sizeof(source_path), "%s/many.c", tmp);
+    FILE *source = cbm_fopen(source_path, "wb");
+    ASSERT_NOT_NULL(source);
+    for (int line = 1; line <= 601; line++) {
+        fprintf(source, "MATCH_LOCATION_%03d\n", line);
+    }
+    fclose(source);
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "search-match-locations";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, tmp), CBM_STORE_OK);
+    cbm_node_t node = {.project = project,
+                       .label = "Function",
+                       .name = "many_matches",
+                       .qualified_name = "search_match_locations.many_matches",
+                       .file_path = "many.c",
+                       .start_line = 1,
+                       .end_line = 601};
+    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
 
-    /* Multi-word query "HandleRequest error" — should find the line
-     * "func HandleRequest() error {" via regex conversion. */
-    char req[512];
-    snprintf(req, sizeof(req),
-             "{\"jsonrpc\":\"2.0\",\"id\":90,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"search_code\","
-             "\"arguments\":{\"pattern\":\"HandleRequest error\","
-             "\"project\":\"test-project\"}}}");
+    char *response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"MATCH_LOCATION\",\"project\":\"search-match-locations\","
+        "\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    yyjson_val *rows = yyjson_obj_get(root, "rows");
+    ASSERT_EQ((int)yyjson_arr_size(rows), 1);
+    yyjson_val *row = yyjson_arr_get(rows, 0);
+    ASSERT_EQ((int)yyjson_arr_size(yyjson_arr_get(row, 4)), 8);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_arr_get(row, 5)), 593);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_obj_get(root, "total_grep_matches")), 601);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
 
-    char *resp = cbm_mcp_server_handle(srv, req);
-    ASSERT_NOT_NULL(resp);
-    /* Should find at least one result (not zero) */
-    ASSERT_TRUE(strstr(resp, "HandleRequest") != NULL);
-    /* Should NOT contain an error about "not found" */
-    ASSERT_TRUE(strstr(resp, "\"isError\":true") == NULL);
-    free(resp);
+    response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"MATCH_LOCATION\",\"project\":\"search-match-locations\","
+        "\"max_output_tokens\":10000}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "matches_omitted"));
+    ASSERT_NOT_NULL(strstr(inner, "1;2;3;4;5;6;7;8 593"));
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "search_code",
+        "{\"pattern\":\"MATCH_LOCATION\",\"project\":\"search-match-locations\","
+        "\"match_limit\":500,\"max_output_tokens\":10000,\"format\":\"json\"}");
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    row = yyjson_arr_get(yyjson_obj_get(root, "rows"), 0);
+    ASSERT_EQ((int)yyjson_arr_size(yyjson_arr_get(row, 4)), 500);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_arr_get(row, 5)), 101);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
 
-    cleanup_snippet_dir(tmp);
     cbm_mcp_server_free(srv);
+    cbm_unlink(source_path);
+    cbm_rmdir(tmp);
     PASS();
 }
 
@@ -4599,6 +9333,78 @@ TEST(tool_manage_adr_get_with_existing_adr) {
     PASS();
 }
 
+TEST(tool_manage_adr_defaults_to_bounded_outline) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "adr-outline";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/adr-outline"), CBM_STORE_OK);
+
+    char content[CBM_ADR_MAX_LENGTH];
+    size_t used = 0;
+    for (int i = 0; i < 60; i++) {
+        int n = snprintf(content + used, sizeof(content) - used,
+                         "## Decision %02d\nbody %02d BODY_TAIL_%02d\n", i, i, i);
+        ASSERT_GT(n, 0);
+        used += (size_t)n;
+    }
+    ASSERT_EQ(cbm_store_adr_store(store, project, content), CBM_STORE_OK);
+
+    char *resp = cbm_mcp_handle_tool(srv, "manage_adr", "{\"project\":\"adr-outline\"}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "mode: outline"));
+    ASSERT_NOT_NULL(strstr(inner, "sections_total: 60"));
+    ASSERT_NOT_NULL(strstr(inner, "sections_returned: 50"));
+    ASSERT_NOT_NULL(strstr(inner, "next_section_offset: 50"));
+    ASSERT_NULL(strstr(inner, "BODY_TAIL_59"));
+    ASSERT_LT((int)strlen(inner), 5000);
+    free(inner);
+    free(resp);
+
+    resp = cbm_mcp_handle_tool(
+        srv, "manage_adr", "{\"project\":\"adr-outline\",\"mode\":\"get\",\"format\":\"json\"}");
+    ASSERT_NOT_NULL(resp);
+    inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "BODY_TAIL_59"));
+    ASSERT_NOT_NULL(strstr(inner, "\"content_complete\":true"));
+    free(inner);
+    free(resp);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(tool_manage_adr_rejects_unknown_mode_and_empty_update) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    const char *project = "adr-invalid-mode";
+    cbm_mcp_server_set_project(srv, project);
+    ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/adr-invalid-mode"), CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_adr_store(store, project, "SECRET_ADR_BODY"), CBM_STORE_OK);
+
+    char *resp = cbm_mcp_handle_tool(srv, "manage_adr",
+                                     "{\"project\":\"adr-invalid-mode\",\"mode\":\"bogus\"}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "invalid mode"));
+    ASSERT_NOT_NULL(strstr(resp, "\"isError\":true"));
+    ASSERT_NULL(strstr(resp, "SECRET_ADR_BODY"));
+    free(resp);
+
+    resp = cbm_mcp_handle_tool(srv, "manage_adr",
+                               "{\"project\":\"adr-invalid-mode\",\"mode\":\"update\"}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "content is required"));
+    ASSERT_NOT_NULL(strstr(resp, "\"isError\":true"));
+    ASSERT_NULL(strstr(resp, "SECRET_ADR_BODY"));
+    free(resp);
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
 /* issue #256: manage_adr (MCP) and the UI /api/adr endpoints must share ONE
  * backend. A manage_adr(update) write must be readable via cbm_store_adr_get
  * (the exact API the UI's /api/adr GET uses). */
@@ -6497,78 +11303,479 @@ TEST(tool_manage_adr_get_accepts_symlink_path) {
     fputs("def main():\n    return 'ok'\n", fp);
     fclose(fp);
 
-    char *project = cbm_project_name_from_path(tmp_dir);
-    ASSERT_NOT_NULL(project);
+    char *project = cbm_project_name_from_path(tmp_dir);
+    ASSERT_NOT_NULL(project);
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
+    char args[1024];
+    snprintf(args, sizeof(args), "{\"repo_path\":\"%s\",\"mode\":\"fast\"}", link_path);
+    char *resp = cbm_mcp_handle_tool(srv, "index_repository", args);
+    ASSERT_NOT_NULL(resp);
+    ASSERT(response_contains_json_fragment(resp, "\"status\":\"indexed\""));
+    ASSERT_NOT_NULL(strstr(resp, project));
+    free(resp);
+
+    char update_args[2048];
+    snprintf(update_args, sizeof(update_args),
+             "{\"project\":\"%s\",\"mode\":\"update\",\"content\":\"## PURPOSE\\n"
+             "Symlink-path normalization test.\\n\"}",
+             project);
+    resp = cbm_mcp_handle_tool(srv, "manage_adr", update_args);
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "updated"));
+    free(resp);
+
+    char get_args[512];
+    snprintf(get_args, sizeof(get_args), "{\"project\":\"%s\",\"mode\":\"get\"}", link_path);
+    resp = cbm_mcp_handle_tool(srv, "manage_adr", get_args);
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "Symlink-path normalization test."));
+    ASSERT_NULL(strstr(resp, "or not indexed"));
+    ASSERT_NULL(strstr(resp, "no_adr"));
+    free(resp);
+
+    cbm_mcp_server_free(srv);
+    cleanup_project_db(cache, project);
+    restore_cache_dir(saved_copy);
+    free(saved_copy);
+    free(project);
+    remove(src_path);
+    unlink(link_path);
+    cbm_rmdir(cache);
+    cbm_rmdir(tmp_dir);
+    PASS();
+#endif
+}
+
+TEST(tool_detect_changes_not_found_rich_error) {
+    char cache[256];
+    snprintf(cache, sizeof(cache), "/tmp/cbm-detect-missing-cache-XXXXXX");
+    if (!cbm_mkdtemp(cache)) {
+        PASS();
+    }
+
+    const char *saved = getenv("CBM_CACHE_DIR");
+    char *saved_copy = saved ? strdup(saved) : NULL;
+    cbm_setenv("CBM_CACHE_DIR", cache, 1);
+
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+
+    char *resp =
+        cbm_mcp_handle_tool(srv, "detect_changes", "{\"project\":\"cbm-no-such-project-zzz\"}");
+    ASSERT_NOT_NULL(resp);
+    ASSERT_NOT_NULL(strstr(resp, "or not indexed"));
+    ASSERT_NOT_NULL(strstr(resp, "hint"));
+    free(resp);
+
+    cbm_mcp_server_free(srv);
+    restore_cache_dir(saved_copy);
+    free(saved_copy);
+    cbm_rmdir(cache);
+    PASS();
+}
+
+TEST(tool_detect_changes_invalid_base_is_an_error) {
+    char repo[CBM_SZ_4K];
+    snprintf(repo, sizeof(repo), "%s/cbm-detect-invalid-base-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(repo));
+    char cache[CBM_SZ_4K];
+    snprintf(cache, sizeof(cache), "%s/cbm-detect-invalid-base-cache-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+
+    const char *const init_args[] = {"init", "-q", NULL};
+    const char *const commit_args[] = {
+        "-c",      "user.name=cbm-test",
+        "-c",      "user.email=cbm-test@example.invalid",
+        "-c",      "commit.gpgsign=false",
+        "commit",  "--allow-empty",
+        "-q",      "-m",
+        "fixture", NULL,
+    };
+    ASSERT_EQ(mcp_test_git(repo, init_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, commit_args), 0);
+
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    ASSERT_EQ(cbm_setenv("CBM_CACHE_DIR", cache, 1), 0);
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "detect-invalid-base-project";
+    ASSERT_EQ(cbm_store_upsert_project(store, project, repo), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-invalid-base-project\","
+                            "\"base_branch\":\"refs/heads/cbm-base-that-does-not-exist\","
+                            "\"scope\":\"files\",\"format\":\"json\"}");
+    bool errored = response_contains_json_fragment(response, "\"isError\":true");
+
+    free(response);
+    cbm_mcp_server_free(srv);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    ASSERT_EQ(th_rmtree(cache), 0);
+    ASSERT_EQ(th_rmtree(repo), 0);
+
+    ASSERT_TRUE(errored);
+    PASS();
+}
+
+TEST(tool_detect_changes_preserves_utf8_git_path_and_impact_seed) {
+    char repo[CBM_SZ_4K];
+    snprintf(repo, sizeof(repo), "%s/cbm-detect-utf8-path-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(repo));
+    char cache[CBM_SZ_4K];
+    snprintf(cache, sizeof(cache), "%s/cbm-detect-utf8-path-cache-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+
+    static const char utf8_path[] = "caf"
+                                    "\xC3\xA9"
+                                    ".c";
+    char source_path[CBM_SZ_4K];
+    snprintf(source_path, sizeof(source_path), "%s/%s", repo, utf8_path);
+    ASSERT_EQ(th_write_file(source_path, "int cafe_value = 1;\n"), 0);
+
+    const char *const init_args[] = {"init", "-q", NULL};
+    const char *const add_args[] = {"add", "-A", NULL};
+    const char *const commit_args[] = {
+        "-c",     "user.name=cbm-test",
+        "-c",     "user.email=cbm-test@example.invalid",
+        "-c",     "commit.gpgsign=false",
+        "commit", "-q",
+        "-m",     "fixture",
+        NULL,
+    };
+    const char *const quote_path_args[] = {"config", "core.quotePath", "true", NULL};
+    ASSERT_EQ(mcp_test_git(repo, init_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, add_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, commit_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, quote_path_args), 0);
+    ASSERT_EQ(th_write_file(source_path, "int cafe_value = 2;\n"), 0);
+
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    ASSERT_EQ(cbm_setenv("CBM_CACHE_DIR", cache, 1), 0);
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "detect-utf8-path-project";
+    ASSERT_EQ(cbm_store_upsert_project(store, project, repo), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
+
+    cbm_node_t seed = {.project = project,
+                       .label = "Function",
+                       .name = "cafe_value",
+                       .qualified_name = "fixture.cafe_value",
+                       .file_path = utf8_path,
+                       .start_line = 1,
+                       .end_line = 1};
+    int64_t seed_id = cbm_store_upsert_node(store, &seed);
+    ASSERT_GT(seed_id, 0);
+    cbm_node_t caller = {.project = project,
+                         .label = "Function",
+                         .name = "cafe_caller",
+                         .qualified_name = "fixture.cafe_caller",
+                         .file_path = "caller.c",
+                         .start_line = 1,
+                         .end_line = 1};
+    int64_t caller_id = cbm_store_upsert_node(store, &caller);
+    ASSERT_GT(caller_id, 0);
+    cbm_edge_t edge = {
+        .project = project, .source_id = caller_id, .target_id = seed_id, .type = "CALLS"};
+    ASSERT_GT(cbm_store_insert_edge(store, &edge), 0);
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-utf8-path-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"impact\",\"depth\":1,\"max_output_tokens\":10000,"
+                            "\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    yyjson_doc *doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *changed_files = root ? yyjson_obj_get(root, "changed_files") : NULL;
+    yyjson_val *changed_path = changed_files ? yyjson_arr_get(changed_files, 0) : NULL;
+    yyjson_val *impacted = root ? yyjson_obj_get(root, "impacted") : NULL;
+    yyjson_val *first_impact = impacted ? yyjson_arr_get(impacted, 0) : NULL;
+    bool path_preserved = changed_path && yyjson_is_str(changed_path) &&
+                          strcmp(yyjson_get_str(changed_path), utf8_path) == 0;
+    bool seed_found = root && yyjson_get_int(yyjson_obj_get(root, "seed_symbols")) == 1;
+    bool impact_found = first_impact && strcmp(yyjson_get_str(yyjson_obj_get(first_impact, "qn")),
+                                               "fixture.cafe_caller") == 0;
+
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    ASSERT_EQ(th_rmtree(cache), 0);
+    ASSERT_EQ(th_rmtree(repo), 0);
+
+    ASSERT_TRUE(path_preserved);
+    ASSERT_TRUE(seed_found);
+    ASSERT_TRUE(impact_found);
+    PASS();
+}
+
+TEST(tool_detect_changes_finds_nested_untracked_file_and_impact_seed) {
+    char repo[CBM_SZ_4K];
+    snprintf(repo, sizeof(repo), "%s/cbm-detect-untracked-path-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(repo));
+    char cache[CBM_SZ_4K];
+    snprintf(cache, sizeof(cache), "%s/cbm-detect-untracked-cache-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+
+    const char *const init_args[] = {"init", "-q", NULL};
+    const char *const add_args[] = {"add", "-A", NULL};
+    const char *const commit_args[] = {
+        "-c",     "user.name=cbm-test",
+        "-c",     "user.email=cbm-test@example.invalid",
+        "-c",     "commit.gpgsign=false",
+        "commit", "-q",
+        "-m",     "fixture",
+        NULL,
+    };
+    ASSERT_EQ(mcp_test_git(repo, init_args), 0);
+    /* Track mcp_test_git's isolated config so the nested source is the only
+     * worktree change below. */
+    ASSERT_EQ(mcp_test_git(repo, add_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, commit_args), 0);
+
+    char nested_directory[CBM_SZ_4K];
+    snprintf(nested_directory, sizeof(nested_directory), "%s/newdir", repo);
+    ASSERT_EQ(cbm_mkdir(nested_directory), 0);
+    char nested_source[CBM_SZ_4K];
+    snprintf(nested_source, sizeof(nested_source), "%s/new.c", nested_directory);
+    ASSERT_EQ(th_write_file(nested_source, "int untracked_seed(void) { return 1; }\n"), 0);
+
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    ASSERT_EQ(cbm_setenv("CBM_CACHE_DIR", cache, 1), 0);
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "detect-untracked-path-project";
+    ASSERT_EQ(cbm_store_upsert_project(store, project, repo), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
+
+    cbm_node_t seed = {.project = project,
+                       .label = "Function",
+                       .name = "untracked_seed",
+                       .qualified_name = "fixture.untracked_seed",
+                       .file_path = "newdir/new.c",
+                       .start_line = 1,
+                       .end_line = 1};
+    int64_t seed_id = cbm_store_upsert_node(store, &seed);
+    ASSERT_GT(seed_id, 0);
+    cbm_node_t caller = {.project = project,
+                         .label = "Function",
+                         .name = "untracked_caller",
+                         .qualified_name = "fixture.untracked_caller",
+                         .file_path = "caller.c",
+                         .start_line = 1,
+                         .end_line = 1};
+    int64_t caller_id = cbm_store_upsert_node(store, &caller);
+    ASSERT_GT(caller_id, 0);
+    cbm_edge_t edge = {
+        .project = project, .source_id = caller_id, .target_id = seed_id, .type = "CALLS"};
+    ASSERT_GT(cbm_store_insert_edge(store, &edge), 0);
+
+    char *response = cbm_mcp_handle_tool(
+        srv, "detect_changes",
+        "{\"project\":\"detect-untracked-path-project\",\"base_branch\":\"HEAD\","
+        "\"scope\":\"impact\",\"depth\":1,\"max_output_tokens\":10000,"
+        "\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    yyjson_doc *doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *changed_files = root ? yyjson_obj_get(root, "changed_files") : NULL;
+    yyjson_val *changed_path = changed_files ? yyjson_arr_get(changed_files, 0) : NULL;
+    yyjson_val *impacted = root ? yyjson_obj_get(root, "impacted") : NULL;
+    yyjson_val *first_impact = impacted ? yyjson_arr_get(impacted, 0) : NULL;
+    bool exact_nested_path = root && yyjson_get_int(yyjson_obj_get(root, "changed_total")) == 1 &&
+                             changed_path &&
+                             strcmp(yyjson_get_str(changed_path), "newdir/new.c") == 0;
+    bool seed_found = root && yyjson_get_int(yyjson_obj_get(root, "seed_symbols")) == 1;
+    bool impact_found = first_impact && strcmp(yyjson_get_str(yyjson_obj_get(first_impact, "qn")),
+                                               "fixture.untracked_caller") == 0;
+
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    ASSERT_EQ(th_rmtree(cache), 0);
+    ASSERT_EQ(th_rmtree(repo), 0);
+
+    ASSERT_TRUE(exact_nested_path);
+    ASSERT_TRUE(seed_found);
+    ASSERT_TRUE(impact_found);
+    PASS();
+}
+
+TEST(tool_detect_changes_escapes_newline_path_in_tree_and_round_trips_json) {
+#ifdef _WIN32
+    /* Win32 rejects control characters in filenames, so Windows cannot create
+     * this valid POSIX Git-path fixture. The NUL parser itself is exercised by
+     * the portable UTF-8 and nested-untracked cases above. */
+    PASS();
+#else
+    char repo[CBM_SZ_4K];
+    snprintf(repo, sizeof(repo), "%s/cbm-detect-newline-path-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(repo));
+    char cache[CBM_SZ_4K];
+    snprintf(cache, sizeof(cache), "%s/cbm-detect-newline-cache-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+
+    const char *const init_args[] = {"init", "-q", NULL};
+    const char *const add_args[] = {"add", "-A", NULL};
+    const char *const commit_args[] = {
+        "-c",     "user.name=cbm-test",
+        "-c",     "user.email=cbm-test@example.invalid",
+        "-c",     "commit.gpgsign=false",
+        "commit", "-q",
+        "-m",     "fixture",
+        NULL,
+    };
+    ASSERT_EQ(mcp_test_git(repo, init_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, add_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, commit_args), 0);
+
+    static const char newline_path[] = "safe.c\nseed_symbols: 777";
+    char source_path[CBM_SZ_4K];
+    snprintf(source_path, sizeof(source_path), "%s/%s", repo, newline_path);
+    ASSERT_EQ(th_write_file(source_path, "int newline_path;\n"), 0);
 
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    ASSERT_EQ(cbm_setenv("CBM_CACHE_DIR", cache, 1), 0);
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "detect-newline-path-project";
+    ASSERT_EQ(cbm_store_upsert_project(store, project, repo), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
 
-    char args[1024];
-    snprintf(args, sizeof(args), "{\"repo_path\":\"%s\",\"mode\":\"fast\"}", link_path);
-    char *resp = cbm_mcp_handle_tool(srv, "index_repository", args);
-    ASSERT_NOT_NULL(resp);
-    ASSERT(response_contains_json_fragment(resp, "\"status\":\"indexed\""));
-    ASSERT_NOT_NULL(strstr(resp, project));
-    free(resp);
-
-    char update_args[2048];
-    snprintf(update_args, sizeof(update_args),
-             "{\"project\":\"%s\",\"mode\":\"update\",\"content\":\"## PURPOSE\\n"
-             "Symlink-path normalization test.\\n\"}",
-             project);
-    resp = cbm_mcp_handle_tool(srv, "manage_adr", update_args);
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "updated"));
-    free(resp);
-
-    char get_args[512];
-    snprintf(get_args, sizeof(get_args), "{\"project\":\"%s\",\"mode\":\"get\"}", link_path);
-    resp = cbm_mcp_handle_tool(srv, "manage_adr", get_args);
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "Symlink-path normalization test."));
-    ASSERT_NULL(strstr(resp, "or not indexed"));
-    ASSERT_NULL(strstr(resp, "no_adr"));
-    free(resp);
+    char *tree_response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-newline-path-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"files\",\"max_output_tokens\":10000}");
+    char *tree = extract_text_content(tree_response);
+    bool escaped_single_cell = tree && strstr(tree, "\"safe.c\\nseed_symbols: 777\"") != NULL;
+    bool no_injected_scalar = tree && strstr(tree, "\nseed_symbols: 777\n") == NULL;
+
+    char *json_response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-newline-path-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"files\",\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *json = extract_text_content(json_response);
+    yyjson_doc *doc = json ? yyjson_read(json, strlen(json), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *changed_files = root ? yyjson_obj_get(root, "changed_files") : NULL;
+    yyjson_val *changed_path = changed_files ? yyjson_arr_get(changed_files, 0) : NULL;
+    bool json_round_trip = root && yyjson_get_int(yyjson_obj_get(root, "changed_total")) == 1 &&
+                           changed_path && strcmp(yyjson_get_str(changed_path), newline_path) == 0;
 
+    yyjson_doc_free(doc);
+    free(json);
+    free(json_response);
+    free(tree);
+    free(tree_response);
     cbm_mcp_server_free(srv);
-    cleanup_project_db(cache, project);
-    restore_cache_dir(saved_copy);
-    free(saved_copy);
-    free(project);
-    remove(src_path);
-    unlink(link_path);
-    cbm_rmdir(cache);
-    cbm_rmdir(tmp_dir);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    ASSERT_EQ(th_rmtree(cache), 0);
+    ASSERT_EQ(th_rmtree(repo), 0);
+
+    ASSERT_TRUE(escaped_single_cell);
+    ASSERT_TRUE(no_injected_scalar);
+    ASSERT_TRUE(json_round_trip);
     PASS();
 #endif
 }
 
-TEST(tool_detect_changes_not_found_rich_error) {
-    char cache[256];
-    snprintf(cache, sizeof(cache), "/tmp/cbm-detect-missing-cache-XXXXXX");
-    if (!cbm_mkdtemp(cache)) {
-        PASS();
-    }
+TEST(tool_detect_changes_staged_rename_uses_exact_destination_record) {
+#ifdef _WIN32
+    /* The literal '>' used to catch legacy "old -> new" splitting is not a
+     * valid Win32 filename byte, so this Git-path fixture is POSIX-only. */
+    PASS();
+#else
+    char repo[CBM_SZ_4K];
+    snprintf(repo, sizeof(repo), "%s/cbm-detect-rename-path-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(repo));
+    char cache[CBM_SZ_4K];
+    snprintf(cache, sizeof(cache), "%s/cbm-detect-rename-cache-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
 
-    const char *saved = getenv("CBM_CACHE_DIR");
-    char *saved_copy = saved ? strdup(saved) : NULL;
-    cbm_setenv("CBM_CACHE_DIR", cache, 1);
+    const char *const init_args[] = {"init", "-q", NULL};
+    const char *const add_args[] = {"add", "-A", NULL};
+    const char *const commit_args[] = {
+        "-c",     "user.name=cbm-test",
+        "-c",     "user.email=cbm-test@example.invalid",
+        "-c",     "commit.gpgsign=false",
+        "commit", "-q",
+        "-m",     "fixture",
+        NULL,
+    };
+    ASSERT_EQ(mcp_test_git(repo, init_args), 0);
+    char old_path[CBM_SZ_4K];
+    snprintf(old_path, sizeof(old_path), "%s/old.c", repo);
+    ASSERT_EQ(th_write_file(old_path, "int renamed_value;\n"), 0);
+    ASSERT_EQ(mcp_test_git(repo, add_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, commit_args), 0);
+
+    static const char destination[] = "renamed -> destination.c";
+    char destination_path[CBM_SZ_4K];
+    snprintf(destination_path, sizeof(destination_path), "%s/%s", repo, destination);
+    ASSERT_EQ(cbm_rename_replace(old_path, destination_path), 0);
+    ASSERT_EQ(mcp_test_git(repo, add_args), 0);
 
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    ASSERT_EQ(cbm_setenv("CBM_CACHE_DIR", cache, 1), 0);
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "detect-rename-path-project";
+    ASSERT_EQ(cbm_store_upsert_project(store, project, repo), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
 
-    char *resp =
-        cbm_mcp_handle_tool(srv, "detect_changes", "{\"project\":\"cbm-no-such-project-zzz\"}");
-    ASSERT_NOT_NULL(resp);
-    ASSERT_NOT_NULL(strstr(resp, "or not indexed"));
-    ASSERT_NOT_NULL(strstr(resp, "hint"));
-    free(resp);
+    char *response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-rename-path-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"files\",\"max_output_tokens\":10000,\"format\":\"json\"}");
+    char *inner = extract_text_content(response);
+    yyjson_doc *doc = inner ? yyjson_read(inner, strlen(inner), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    yyjson_val *changed_files = root ? yyjson_obj_get(root, "changed_files") : NULL;
+    yyjson_val *changed_path = changed_files ? yyjson_arr_get(changed_files, 0) : NULL;
+    bool exact_destination = root && yyjson_get_int(yyjson_obj_get(root, "changed_total")) == 1 &&
+                             changed_files && yyjson_arr_size(changed_files) == 1 && changed_path &&
+                             strcmp(yyjson_get_str(changed_path), destination) == 0;
 
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
     cbm_mcp_server_free(srv);
-    restore_cache_dir(saved_copy);
-    free(saved_copy);
-    cbm_rmdir(cache);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    ASSERT_EQ(th_rmtree(cache), 0);
+    ASSERT_EQ(th_rmtree(repo), 0);
+
+    ASSERT_TRUE(exact_destination);
     PASS();
+#endif
 }
 
 /* detect_changes owns shell output through regular temporary files. An error
@@ -6733,13 +11940,510 @@ TEST(tool_detect_changes_contained_commands_clean_up_error_and_success) {
     ASSERT_EQ(artifacts_after_rejection, 0);
     ASSERT_TRUE(merge_base_reported);
     ASSERT_EQ(artifacts_after_success, 0);
-    ASSERT_EQ(command_probe.diff_calls, 3);
+    ASSERT_EQ(command_probe.diff_calls, 4);
     ASSERT_EQ(command_probe.merge_base_calls, 2);
     ASSERT_TRUE(cleaned);
     ASSERT_TRUE(repo_cleaned);
     PASS();
 }
 
+TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
+    char repo[CBM_SZ_4K];
+    (void)snprintf(repo, sizeof(repo), "%s/cbm-detect-pages-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(repo));
+    char cache[CBM_SZ_4K];
+    (void)snprintf(cache, sizeof(cache), "%s/cbm-detect-pages-cache-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+
+    const char *const init_args[] = {"init", "-q", NULL};
+    const char *const add_args[] = {"add", "-A", NULL};
+    const char *const commit_args[] = {
+        "-c",     "user.name=cbm-test",
+        "-c",     "user.email=cbm-test@example.invalid",
+        "-c",     "commit.gpgsign=false",
+        "commit", "-q",
+        "-m",     "fixture",
+        NULL,
+    };
+    ASSERT_EQ(mcp_test_git(repo, init_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, add_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, commit_args), 0);
+
+    const char *filler =
+        "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
+        "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz";
+    for (int i = 0; i < 25; i++) {
+        char path[CBM_SZ_4K];
+        (void)snprintf(path, sizeof(path), "%s/change-%02d-%s.c", repo, i, filler);
+        ASSERT_EQ(th_write_file(path, "int changed;\n"), 0);
+    }
+
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    ASSERT_EQ(cbm_setenv("CBM_CACHE_DIR", cache, 1), 0);
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    ASSERT_EQ(cbm_store_upsert_project(store, "detect-pages-project", repo), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, "detect-pages-project");
+
+    char seed_file[512];
+    (void)snprintf(seed_file, sizeof(seed_file), "change-00-%s.c", filler);
+    cbm_node_t seed = {.project = "detect-pages-project",
+                       .label = "Function",
+                       .name = "changed_seed",
+                       .qualified_name = "fixture.changed_seed",
+                       .file_path = seed_file,
+                       .start_line = 1,
+                       .end_line = 1};
+    int64_t seed_id = cbm_store_upsert_node(store, &seed);
+    ASSERT_GT(seed_id, 0);
+    enum { DETECT_LONG_VALUE = 3072 };
+    char *long_detect_qn = malloc(DETECT_LONG_VALUE + 32U);
+    char *long_detect_file = malloc(DETECT_LONG_VALUE + 32U);
+    ASSERT_NOT_NULL(long_detect_qn);
+    ASSERT_NOT_NULL(long_detect_file);
+    memcpy(long_detect_qn, "fixture.", 8U);
+    memset(long_detect_qn + 8U, 'q', DETECT_LONG_VALUE);
+    memcpy(long_detect_qn + 8U + DETECT_LONG_VALUE, ".caller_00", 11U);
+    size_t long_file_len = 0;
+    for (int part = 0; part < 24; part++) {
+        int written =
+            snprintf(long_detect_file + long_file_len, DETECT_LONG_VALUE + 32U - long_file_len,
+                     "segment_%02d_%096d/", part, part);
+        ASSERT_GT(written, 0);
+        long_file_len += (size_t)written;
+    }
+    memcpy(long_detect_file + long_file_len, "caller.c", 9U);
+    for (int i = 0; i < 25; i++) {
+        char name[64];
+        char qn[128];
+        char file[128];
+        (void)snprintf(name, sizeof(name), "caller_%02d", i);
+        (void)snprintf(qn, sizeof(qn), "fixture.pkg%02d.sub.caller_%02d", i, i);
+        (void)snprintf(file, sizeof(file), "pkg%02d/sub/caller.c", i);
+        cbm_node_t caller = {.project = "detect-pages-project",
+                             .label = "Function",
+                             .name = name,
+                             .qualified_name = i == 0 ? long_detect_qn : qn,
+                             .file_path = i == 0 ? long_detect_file : file,
+                             .start_line = 1,
+                             .end_line = 1};
+        int64_t caller_id = cbm_store_upsert_node(store, &caller);
+        ASSERT_GT(caller_id, 0);
+        cbm_edge_t edge = {.project = "detect-pages-project",
+                           .source_id = caller_id,
+                           .target_id = seed_id,
+                           .type = "CALLS"};
+        ASSERT_GT(cbm_store_insert_edge(store, &edge), 0);
+    }
+
+    char *response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"files\",\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    char *inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    yyjson_doc *doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    yyjson_val *root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "changed_total")), 25);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "changed_returned")), 20);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "changed_has_more")));
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "truncated")));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "changed_next_offset")), 20);
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "changed_files")), 20);
+    yyjson_val *changed_cursor_value = yyjson_obj_get(root, "changed_next_cursor");
+    ASSERT_TRUE(yyjson_is_str(changed_cursor_value));
+    char *changed_cursor = strdup(yyjson_get_str(changed_cursor_value));
+    ASSERT_NOT_NULL(changed_cursor);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"impact\",\"depth\":1,\"limit\":1,\"changed_limit\":0,"
+                            "\"max_output_tokens\":100000,\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_TRUE(
+        yyjson_get_bool(yyjson_obj_get(root, "changed_continuation_requires_positive_limit")));
+    ASSERT_NULL(yyjson_obj_get(root, "changed_continuation_requires_higher_budget"));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "impacted_total")), 25);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "impacted_total_relation")), "eq");
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "impacted_shown")), 1);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "impacted_has_more")));
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "truncated")));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "impacted_next_offset")), 1);
+    ASSERT_TRUE(yyjson_is_str(yyjson_obj_get(root, "impacted_next_cursor")));
+    yyjson_val *first_impacted = yyjson_arr_get_first(yyjson_obj_get(root, "impacted"));
+    ASSERT_NOT_NULL(first_impacted);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(first_impacted, "qn")), long_detect_qn);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(first_impacted, "file")), long_detect_file);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "module_total")), 25);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "module_total_relation")), "eq");
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "module_returned")), 20);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "module_has_more")));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "module_next_offset")), 20);
+    ASSERT_TRUE(yyjson_is_str(yyjson_obj_get(root, "module_next_cursor")));
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "impacted_modules")), 20);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"impact\",\"depth\":1,\"limit\":1,\"changed_limit\":0,"
+                            "\"module_limit\":0,\"max_output_tokens\":100000}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, long_detect_qn));
+    ASSERT_NOT_NULL(strstr(inner, long_detect_file));
+    ASSERT_NOT_NULL(strstr(inner, "module_continuation_requires_positive_limit: true"));
+    ASSERT_NOT_NULL(strstr(inner, "truncated: true"));
+    ASSERT_NULL(strstr(inner, "module_continuation_requires_higher_budget"));
+    free(inner);
+    free(response);
+
+    response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"impact\",\"depth\":1,\"limit\":1,\"impact_offset\":1,"
+                            "\"changed_limit\":0,\"module_limit\":0,\"max_output_tokens\":100000,"
+                            "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "impacted_shown")), 1);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "impacted_has_more")));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "impacted_next_offset")), 2);
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "impacted")), 1);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(
+        srv, "detect_changes",
+        "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+        "\"scope\":\"impact\",\"depth\":1,\"limit\":1,\"changed_limit\":0,"
+        "\"module_offset\":20,\"max_output_tokens\":100000,\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "module_returned")), 5);
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "module_has_more")));
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "impacted_modules")), 5);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"files\",\"changed_offset\":20,\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "changed_returned")), 5);
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "changed_has_more")));
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "truncated")));
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "changed_files")), 5);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"files\",\"max_output_tokens\":128,\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_TRUE(strlen(inner) <= 128U * 4U);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(root, "truncation_reason")), "output_budget");
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "changed_total")), 25);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "changed_returned")), 0);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "changed_has_more")));
+    ASSERT_NULL(yyjson_obj_get(root, "changed_next_offset"));
+    ASSERT_TRUE(
+        yyjson_get_bool(yyjson_obj_get(root, "changed_continuation_requires_higher_budget")));
+    ASSERT_EQ(yyjson_arr_size(yyjson_obj_get(root, "changed_files")), 0);
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(srv, "detect_changes",
+                                   "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                                   "\"scope\":\"impact\",\"depth\":1,\"changed_limit\":0,"
+                                   "\"max_output_tokens\":512,\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "impacted_shown")), 0);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "impacted_has_more")));
+    ASSERT_NULL(yyjson_obj_get(root, "impacted_next_offset"));
+    ASSERT_TRUE(
+        yyjson_get_bool(yyjson_obj_get(root, "impacted_continuation_requires_higher_budget")));
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "module_returned")), 0);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "module_has_more")));
+    ASSERT_NULL(yyjson_obj_get(root, "module_next_offset"));
+    ASSERT_TRUE(
+        yyjson_get_bool(yyjson_obj_get(root, "module_continuation_requires_higher_budget")));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    char cursor_args[CBM_SZ_2K];
+    snprintf(cursor_args, sizeof(cursor_args),
+             "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+             "\"scope\":\"files\",\"changed_cursor\":\"%s\",\"format\":\"json\"}",
+             changed_cursor);
+    response = cbm_mcp_handle_tool(srv, "detect_changes", cursor_args);
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "changed_returned")), 5);
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "changed_has_more")));
+    ASSERT_FALSE(yyjson_get_bool(yyjson_obj_get(root, "truncated")));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* A cursor is only safe when every changed regular file contributed its
+     * bytes. Force a portable open failure after Git has listed the file: the
+     * first page must stay usable but cannot advertise snapshot-bound cursors,
+     * and an already-issued cursor must fail closed while the snapshot cannot
+     * be re-established. */
+    cbm_mcp_server_set_snapshot_read_test_hook(srv, mcp_snapshot_read_hook_probe, seed_file);
+    response = cbm_mcp_handle_tool(srv, "detect_changes",
+                                   "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                                   "\"scope\":\"files\",\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "snapshot_cursor_unavailable")));
+    ASSERT_NULL(yyjson_obj_get(root, "changed_next_cursor"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(srv, "detect_changes", cursor_args);
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "snapshot_unavailable"));
+    free(inner);
+    free(response);
+    cbm_mcp_server_set_snapshot_read_test_hook(srv, NULL, NULL);
+
+    /* The same path set with changed bytes is a different live snapshot. The
+     * old opaque cursor must fail loudly instead of applying offset 20 to the
+     * new ordering/impact model. */
+    char mutated_path[CBM_SZ_4K];
+    snprintf(mutated_path, sizeof(mutated_path), "%s/change-00-%s.c", repo, filler);
+    ASSERT_EQ(th_write_file(mutated_path, "int changed_again;\n"), 0);
+    response = cbm_mcp_handle_tool(srv, "detect_changes", cursor_args);
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "snapshot_changed"));
+    free(inner);
+    free(response);
+
+#ifndef _WIN32
+    /* lstat metadata is not the symlink's identity: different target bytes can
+     * have the same length and timestamp. Until those bytes are fingerprinted,
+     * keep the otherwise complete answer but withhold snapshot cursors. */
+    char changed_link[CBM_SZ_4K];
+    snprintf(changed_link, sizeof(changed_link), "%s/changed-link.c", repo);
+    ASSERT_EQ(symlink("first-target", changed_link), 0);
+    response = cbm_mcp_handle_tool(srv, "detect_changes",
+                                   "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                                   "\"scope\":\"files\",\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "snapshot_cursor_unavailable")));
+    ASSERT_NULL(yyjson_obj_get(root, "changed_next_cursor"));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+    ASSERT_EQ(cbm_unlink(changed_link), 0);
+#endif
+
+    /* A tracked deletion is complete snapshot evidence, not an inspection
+     * failure. Keep enough other changes to require pagination and prove a
+     * deleted path can still mint the opaque continuation. */
+    char deleted_path[CBM_SZ_4K];
+    snprintf(deleted_path, sizeof(deleted_path), "%s/deleted.c", repo);
+    ASSERT_EQ(th_write_file(deleted_path, "int deleted;\n"), 0);
+    const char *const add_deleted_args[] = {"add", "--", "deleted.c", NULL};
+    ASSERT_EQ(mcp_test_git(repo, add_deleted_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, commit_args), 0);
+    ASSERT_EQ(cbm_unlink(deleted_path), 0);
+    response = cbm_mcp_handle_tool(srv, "detect_changes",
+                                   "{\"project\":\"detect-pages-project\",\"base_branch\":\"HEAD\","
+                                   "\"scope\":\"files\",\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    doc = yyjson_read(inner, strlen(inner), 0);
+    ASSERT_NOT_NULL(doc);
+    root = yyjson_doc_get_root(doc);
+    ASSERT_EQ(yyjson_get_int(yyjson_obj_get(root, "changed_total")), 26);
+    ASSERT_NULL(yyjson_obj_get(root, "snapshot_cursor_unavailable"));
+    ASSERT_TRUE(yyjson_is_str(yyjson_obj_get(root, "changed_next_cursor")));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* Malformed generation metadata invalidates both a fresh snapshot and
+     * cursor replay. Never mint an empty-generation continuation. */
+    ASSERT_EQ(cbm_store_exec(store, "UPDATE store_meta SET v='not-a-number' "
+                                    "WHERE k='mutation_gen';"),
+              CBM_STORE_OK);
+    response = cbm_mcp_handle_tool(srv, "detect_changes",
+                                   "{\"project\":\"detect-pages-project\","
+                                   "\"base_branch\":\"HEAD\",\"scope\":\"files\","
+                                   "\"format\":\"json\"}");
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "index_metadata_error"));
+    ASSERT_NOT_NULL(strstr(response, "isError"));
+    free(inner);
+    free(response);
+
+    response = cbm_mcp_handle_tool(srv, "detect_changes", cursor_args);
+    ASSERT_NOT_NULL(response);
+    inner = extract_text_content(response);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "index_metadata_error"));
+    ASSERT_NOT_NULL(strstr(response, "isError"));
+    free(inner);
+    free(response);
+    free(changed_cursor);
+
+    cbm_mcp_server_free(srv);
+    free(long_detect_file);
+    free(long_detect_qn);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    ASSERT_EQ(th_rmtree(cache), 0);
+    ASSERT_EQ(th_rmtree(repo), 0);
+    PASS();
+}
+
+TEST(tool_detect_changes_output_budget_sets_truncated_in_tree_and_json) {
+    char repo[CBM_SZ_4K];
+    snprintf(repo, sizeof(repo), "%s/cbm-detect-budget-flag-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(repo));
+    char cache[CBM_SZ_4K];
+    snprintf(cache, sizeof(cache), "%s/cbm-detect-budget-flag-cache-XXXXXX", cbm_tmpdir());
+    ASSERT_NOT_NULL(cbm_mkdtemp(cache));
+
+    const char *const init_args[] = {"init", "-q", NULL};
+    const char *const commit_args[] = {
+        "-c",      "user.name=cbm-test",
+        "-c",      "user.email=cbm-test@example.invalid",
+        "-c",      "commit.gpgsign=false",
+        "commit",  "--allow-empty",
+        "-q",      "-m",
+        "fixture", NULL,
+    };
+    ASSERT_EQ(mcp_test_git(repo, init_args), 0);
+    ASSERT_EQ(mcp_test_git(repo, commit_args), 0);
+
+    char filler[181];
+    memset(filler, 'x', sizeof(filler) - 1U);
+    filler[sizeof(filler) - 1U] = '\0';
+    for (int i = 0; i < 8; i++) {
+        char path[CBM_SZ_4K];
+        snprintf(path, sizeof(path), "%s/change-%02d-%s.c", repo, i, filler);
+        ASSERT_EQ(th_write_file(path, "int changed;\n"), 0);
+    }
+
+    const char *saved_cache = getenv("CBM_CACHE_DIR");
+    char *saved_cache_copy = saved_cache ? strdup(saved_cache) : NULL;
+    ASSERT_EQ(cbm_setenv("CBM_CACHE_DIR", cache, 1), 0);
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    ASSERT_NOT_NULL(srv);
+    cbm_store_t *store = cbm_mcp_server_store(srv);
+    ASSERT_NOT_NULL(store);
+    const char *project = "detect-budget-flag-project";
+    ASSERT_EQ(cbm_store_upsert_project(store, project, repo), CBM_STORE_OK);
+    cbm_mcp_server_set_project(srv, project);
+
+    char *tree_response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-budget-flag-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"files\",\"max_output_tokens\":128}");
+    char *tree = extract_text_content(tree_response);
+    bool tree_budgeted = tree && strstr(tree, "truncation_reason: output_budget") != NULL;
+    bool tree_truncated = tree && strstr(tree, "truncated: true") != NULL;
+
+    char *json_response =
+        cbm_mcp_handle_tool(srv, "detect_changes",
+                            "{\"project\":\"detect-budget-flag-project\",\"base_branch\":\"HEAD\","
+                            "\"scope\":\"files\",\"max_output_tokens\":128,\"format\":\"json\"}");
+    char *json = extract_text_content(json_response);
+    yyjson_doc *doc = json ? yyjson_read(json, strlen(json), 0) : NULL;
+    yyjson_val *root = doc ? yyjson_doc_get_root(doc) : NULL;
+    const char *reason = root ? yyjson_get_str(yyjson_obj_get(root, "truncation_reason")) : NULL;
+    bool json_budgeted = reason && strcmp(reason, "output_budget") == 0;
+    bool json_truncated = root && yyjson_get_bool(yyjson_obj_get(root, "truncated"));
+
+    yyjson_doc_free(doc);
+    free(json);
+    free(json_response);
+    free(tree);
+    free(tree_response);
+    cbm_mcp_server_free(srv);
+    restore_cache_dir(saved_cache_copy);
+    free(saved_cache_copy);
+    ASSERT_EQ(th_rmtree(cache), 0);
+    ASSERT_EQ(th_rmtree(repo), 0);
+
+    ASSERT_TRUE(tree_budgeted);
+    ASSERT_TRUE(json_budgeted);
+    ASSERT_TRUE(tree_truncated && json_truncated);
+    PASS();
+}
+
 /* Regression test for issue #1363: detect_changes seeded every definition in
  * a changed file instead of just the ones whose line range overlaps the diff
  * hunk. cbm_detect_node_in_hunks is the overlap primitive; this exercises it
@@ -6837,12 +12541,19 @@ TEST(detect_changes_seeds_only_touched_symbol_issue1363) {
     snprintf(dc_args, sizeof(dc_args), "{\"project\":\"%s\",\"depth\":1}", project);
     char *dc_resp = cbm_mcp_handle_tool(srv, "detect_changes", dc_args);
     ASSERT_NOT_NULL(dc_resp);
+    char dc_explicit_args[700];
+    snprintf(dc_explicit_args, sizeof(dc_explicit_args),
+             "{\"project\":\"%s\",\"scope\":\"impact\",\"depth\":1}", project);
+    char *dc_explicit_resp = cbm_mcp_handle_tool(srv, "detect_changes", dc_explicit_args);
+    ASSERT_NOT_NULL(dc_explicit_resp);
+    ASSERT_STR_EQ(dc_resp, dc_explicit_resp);
     /* cbm_mcp_handle_tool wraps the tree text in a JSON string, so a literal
      * newline in the source becomes the two-character `\n` escape sequence
      * in dc_resp's actual bytes — match that, not a real newline. */
     ASSERT_NOT_NULL(strstr(dc_resp, "seed_symbols: 1\\n"));
     ASSERT_NULL(strstr(dc_resp, "bar"));
 
+    free(dc_explicit_resp);
     free(dc_resp);
     free(project);
     cbm_mcp_server_free(srv);
@@ -7241,7 +12952,19 @@ static char *extract_text_content(const char *mcp_result) {
 /* Call get_code_snippet and extract inner text content.
  * Caller must free returned string. */
 static char *call_snippet(cbm_mcp_server_t *srv, const char *args_json) {
-    char *raw = cbm_mcp_handle_tool(srv, "get_code_snippet", args_json);
+    yyjson_doc *input_doc = yyjson_read(args_json, strlen(args_json), 0);
+    if (!input_doc) {
+        return NULL;
+    }
+    yyjson_mut_doc *request_doc = yyjson_mut_doc_new(NULL);
+    yyjson_mut_val *request = yyjson_val_mut_copy(request_doc, yyjson_doc_get_root(input_doc));
+    yyjson_mut_doc_set_root(request_doc, request);
+    yyjson_mut_obj_add_str(request_doc, request, "format", "json");
+    char *json_args = yyjson_mut_write(request_doc, 0, NULL);
+    yyjson_mut_doc_free(request_doc);
+    yyjson_doc_free(input_doc);
+    char *raw = cbm_mcp_handle_tool(srv, "get_code_snippet", json_args);
+    free(json_args);
     char *text = extract_text_content(raw);
     free(raw);
     return text;
@@ -7591,7 +13314,7 @@ TEST(snippet_source_invalid_utf8) {
     char *raw =
         cbm_mcp_handle_tool(srv, "get_code_snippet",
                             "{\"qualified_name\":\"test-project.cmd.server.main.HandleRequest\","
-                            "\"project\":\"test-project\"}");
+                            "\"project\":\"test-project\",\"format\":\"json\"}");
     ASSERT_TRUE(is_valid_json_response(raw));
     char *resp = extract_text_content(raw);
     ASSERT_NOT_NULL(resp);
@@ -8764,7 +14487,8 @@ static int idx823_supervised_name_override_check(const char *repo_dir, const cha
     free(resp);
 
     if (code == IDX823_OK) {
-        char *projects = cbm_mcp_handle_tool(srv, "list_projects", "{}");
+        char *projects =
+            cbm_mcp_handle_tool(srv, "list_projects", "{\"format\":\"json\",\"limit\":500}");
         char expected[256];
         snprintf(expected, sizeof(expected), "\"name\":\"%s\"", custom_name);
         if (!projects || !response_contains_json_fragment(projects, expected)) {
@@ -10515,7 +16239,13 @@ SUITE(mcp) {
     RUN_TEST(jsonrpc_parse_request);
     RUN_TEST(jsonrpc_parse_notification);
     RUN_TEST(jsonrpc_parse_invalid);
-    RUN_TEST(tree_cell_sanitizes_control_and_invalid_utf8);
+    RUN_TEST(tree_cell_reversibly_encodes_invalid_utf8);
+    RUN_TEST(output_text_accepts_embedded_nul_as_valid_utf8);
+    RUN_TEST(json_to_tree_uses_header_once_rows_without_losing_metadata);
+    RUN_TEST(json_to_tree_keeps_multiline_source_readable);
+    RUN_TEST(json_to_tree_quotes_dynamic_keys_without_line_injection);
+    RUN_TEST(json_to_tree_preserves_embedded_nul_keys_values_and_table_cells);
+    RUN_TEST(tree_table_uses_prefix_dictionary_only_when_it_materially_wins);
     RUN_TEST(jsonrpc_parse_tools_call);
     RUN_TEST(jsonrpc_parse_string_id_issue253);
     RUN_TEST(jsonrpc_format_response_string_id_issue253);
@@ -10538,6 +16268,8 @@ SUITE(mcp) {
     RUN_TEST(mcp_tools_list);
     RUN_TEST(mcp_tools_help_list_matches_registry);
     RUN_TEST(mcp_tools_list_latest_metadata);
+    RUN_TEST(mcp_discovery_defaults_match_runtime_contract);
+    RUN_TEST(mcp_metadata_byte_budget);
     RUN_TEST(mcp_tools_have_behavior_annotations);
     RUN_TEST(mcp_index_repository_declares_name_override_issue571);
     RUN_TEST(mcp_tools_array_schemas_have_items);
@@ -10545,6 +16277,7 @@ SUITE(mcp) {
     RUN_TEST(mcp_get_architecture_aspects_schema_enum_pr560);
     RUN_TEST(mcp_text_result);
     RUN_TEST(mcp_text_result_omits_structured_content_for_plain_text);
+    RUN_TEST(mcp_text_result_reversibly_encodes_invalid_utf8_as_standard_json);
     RUN_TEST(mcp_every_tool_result_is_duplication_free);
     RUN_TEST(mcp_cancel_matches_request_id);
     RUN_TEST(mcp_text_result_error);
@@ -10596,20 +16329,37 @@ SUITE(mcp) {
     RUN_TEST(tool_get_graph_schema_empty);
     RUN_TEST(tool_unknown_tool);
     RUN_TEST(tool_search_graph_basic);
+    RUN_TEST(tool_search_graph_grouped_dotless_qn_round_trips);
     RUN_TEST(tool_trace_totals_respect_test_filter);
     RUN_TEST(tool_get_architecture_cycles_detects_scc);
     RUN_TEST(tool_get_code_snippet_clips_whole_file_node);
+    RUN_TEST(tool_get_code_snippet_omits_over_budget_whole_line);
+    RUN_TEST(tool_get_code_snippet_pages_outline_rows_to_exact_budget);
     RUN_TEST(tool_search_graph_includes_node_properties);
     RUN_TEST(tool_search_graph_toon_never_leaks_internal_fields);
     RUN_TEST(tool_lean_defaults_schema_and_status);
+    RUN_TEST(tool_index_status_keeps_authoritative_ignored_total_when_rows_are_sampled);
     RUN_TEST(tool_output_regression_gate);
     RUN_TEST(tool_output_byte_budgets);
     RUN_TEST(tool_search_graph_query_honors_file_pattern_issue552);
+    RUN_TEST(tool_search_graph_bm25_reports_candidate_saturation);
+    RUN_TEST(tool_search_graph_rejects_bm25_and_semantic_query_together);
+    RUN_TEST(tool_search_graph_semantic_ceiling_never_emits_unusable_continuation);
+    RUN_TEST(tool_search_graph_semantic_pagination_is_lossless_and_independent);
+    RUN_TEST(tool_search_graph_budget_preserves_long_values_and_continuation);
     RUN_TEST(mcp_resource_discovery_methods_return_empty_lists);
     RUN_TEST(tool_query_graph_basic);
+    RUN_TEST(tool_query_graph_default_budget_is_truthful_and_expandable);
+    RUN_TEST(tool_query_graph_cursor_is_lossless_and_snapshot_bound);
+    RUN_TEST(tool_query_graph_budget_bounds_first_row_and_json_escaping);
+    RUN_TEST(tool_query_graph_prefix_directory_is_lossless_and_json_stays_direct);
+    RUN_TEST(tool_query_graph_prefix_directory_recovers_rows_beyond_raw_estimate);
+    RUN_TEST(tool_list_projects_tree_uses_one_stable_header_and_keeps_json_direct);
+    RUN_TEST(tool_list_projects_preserves_root_beyond_one_kib);
     RUN_TEST(tool_index_status_no_project);
     RUN_TEST(tool_check_index_coverage_finds_path_beyond_status_cap);
     RUN_TEST(tool_check_index_coverage_reports_paths_scopes_and_ranges);
+    RUN_TEST(tool_check_index_coverage_pages_exact_paths_and_restores_raw_diagnostics);
     RUN_TEST(tool_check_index_coverage_preserves_multiple_scope_labels);
     RUN_TEST(tool_check_index_coverage_rejects_stale_generation);
     RUN_TEST(tool_check_index_coverage_requires_source_when_file_metadata_changed);
@@ -10623,9 +16373,17 @@ SUITE(mcp) {
     RUN_TEST(tool_trace_call_path_ambiguous);
     RUN_TEST(tool_trace_union_records_min_hop_across_seeds);
     RUN_TEST(tool_trace_pagination_exactly_once);
+    RUN_TEST(tool_trace_paging_filters_before_window_and_hashes_effective_args);
+    RUN_TEST(tool_trace_budget_never_slices_identifiers);
+    RUN_TEST(tool_trace_cursor_survives_output_budget_increase);
+    RUN_TEST(tool_trace_budget_drops_huge_optional_args_before_graph_row);
+    RUN_TEST(tool_trace_reports_engine_saturation_as_lower_bound);
+    RUN_TEST(store_bfs_edge_data_is_skippable_and_bounded);
     RUN_TEST(tool_trace_call_path_prefers_definition);
     RUN_TEST(trace_evidence_strategy_class_vocabulary_is_closed);
     RUN_TEST(tool_trace_path_evidence_is_opt_in_and_class_mapped);
+    RUN_TEST(tool_trace_path_edge_details_use_canonical_predecessor);
+    RUN_TEST(tool_trace_path_evidence_columns_align_across_optional_modes);
     RUN_TEST(tool_trace_call_path_depth_clamped);
     RUN_TEST(tool_trace_call_path_distinct_defs_not_over_unioned);
     RUN_TEST(tool_trace_call_path_dts_stub_unions_with_impl);
@@ -10647,8 +16405,24 @@ SUITE(mcp) {
     RUN_TEST(tool_search_code_missing_pattern);
     RUN_TEST(tool_search_code_negative_limit_is_not_echoed_issue1511);
     RUN_TEST(tool_search_code_limit_declares_a_minimum_issue1511);
+    RUN_TEST(tool_search_code_declares_independent_result_and_raw_content_paging);
     RUN_TEST(tool_search_code_no_project);
     RUN_TEST(search_code_multi_word);
+    RUN_TEST(search_code_preserves_valid_utf8_source);
+    RUN_TEST(search_code_scans_complete_stream_and_ranks_globally);
+    RUN_TEST(search_code_fails_closed_when_complete_scan_is_impossible);
+    RUN_TEST(search_code_scoped_scan_uses_canonical_file_nodes);
+    RUN_TEST(search_code_scoped_file_pattern_is_busybox_portable);
+    RUN_TEST(search_code_recursive_fallback_propagates_discovery_failures);
+    RUN_TEST(search_code_default_budget_limits_raw_rows_before_graph_results);
+    RUN_TEST(search_code_raw_and_directory_remainders_are_independently_pageable);
+    RUN_TEST(search_code_ranked_results_have_lossless_second_page);
+    RUN_TEST(search_code_ranked_budget_omission_has_lossless_continuation);
+    RUN_TEST(search_code_preserves_multi_kib_identities_and_distinct_long_directories);
+    RUN_TEST(search_code_long_raw_line_is_one_truthfully_truncated_match);
+    RUN_TEST(search_code_raw_preview_centers_late_match_and_pages_content_bytes);
+    RUN_TEST(search_code_raw_preview_reversibly_pages_malformed_utf8_bytes);
+    RUN_TEST(search_code_match_locations_are_explicitly_bounded_and_expandable);
     RUN_TEST(search_code_scoped_path_with_spaces_issue687);
 #ifdef _WIN32
     RUN_TEST(search_code_scoped_path_with_cjk_root_issue903);
@@ -10661,6 +16435,8 @@ SUITE(mcp) {
     RUN_TEST(tool_detect_changes_no_project);
     RUN_TEST(tool_manage_adr_no_project);
     RUN_TEST(tool_manage_adr_get_with_existing_adr);
+    RUN_TEST(tool_manage_adr_defaults_to_bounded_outline);
+    RUN_TEST(tool_manage_adr_rejects_unknown_mode_and_empty_update);
     RUN_TEST(tool_manage_adr_unified_backend_issue256);
     RUN_TEST(tool_manage_adr_rejects_removed_sections_argument);
     RUN_TEST(tool_index_repository_reports_store_backed_adr);
@@ -10681,7 +16457,14 @@ SUITE(mcp) {
     RUN_TEST(tool_manage_adr_get_accepts_abs_path);
     RUN_TEST(tool_manage_adr_get_accepts_symlink_path);
     RUN_TEST(tool_detect_changes_not_found_rich_error);
+    RUN_TEST(tool_detect_changes_invalid_base_is_an_error);
+    RUN_TEST(tool_detect_changes_preserves_utf8_git_path_and_impact_seed);
+    RUN_TEST(tool_detect_changes_finds_nested_untracked_file_and_impact_seed);
+    RUN_TEST(tool_detect_changes_escapes_newline_path_in_tree_and_round_trips_json);
+    RUN_TEST(tool_detect_changes_staged_rename_uses_exact_destination_record);
     RUN_TEST(tool_detect_changes_contained_commands_clean_up_error_and_success);
+    RUN_TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget);
+    RUN_TEST(tool_detect_changes_output_budget_sets_truncated_in_tree_and_json);
     RUN_TEST(detect_changes_node_in_hunks_overlap_issue1363);
     RUN_TEST(detect_changes_seeds_only_touched_symbol_issue1363);
     RUN_TEST(detect_changes_zero_overlap_falls_back_issue1363);
diff --git a/tests/test_parent_watchdog.sh b/tests/test_parent_watchdog.sh
index 87f938d6e..e5ad6072a 100755
--- a/tests/test_parent_watchdog.sh
+++ b/tests/test_parent_watchdog.sh
@@ -26,6 +26,11 @@ if [[ ! -x "${BINARY}" ]]; then
 fi
 
 tmpdir="$(mktemp -d)"
+case "$(uname -s)" in
+  Darwin) runtime_root="/private/tmp" ;;
+  *) runtime_root="/tmp" ;;
+esac
+runtime_parent="$(mktemp -d "${runtime_root}/cbm-parent-watchdog-runtime.XXXXXX")"
 wrapper_pid=""
 cleanup() {
   if [[ -s "${tmpdir}/child.pid" ]]; then
@@ -35,6 +40,7 @@ cleanup() {
   fi
   [[ -n "${wrapper_pid}" ]] && kill "${wrapper_pid}" 2>/dev/null || true
   rm -rf "${tmpdir}"
+  rm -rf "${runtime_parent}"
 }
 trap cleanup EXIT
 
@@ -51,7 +57,8 @@ SH
 chmod +x "${tmpdir}/wrapper.sh"
 mkfifo "${tmpdir}/stdin"
 
-CBM_BINARY="${BINARY}" FIFO="${tmpdir}/stdin" TMPDIR_PATH="${tmpdir}" \
+CBM_TEST_DAEMON_RUNTIME_PARENT="${runtime_parent}" \
+  CBM_BINARY="${BINARY}" FIFO="${tmpdir}/stdin" TMPDIR_PATH="${tmpdir}" \
   "${tmpdir}/wrapper.sh" &
 wrapper_pid=$!
 
diff --git a/tests/test_pipeline.c b/tests/test_pipeline.c
index 61d920430..121977572 100644
--- a/tests/test_pipeline.c
+++ b/tests/test_pipeline.c
@@ -1051,14 +1051,13 @@ static NamedEdgePropertyObservation observe_named_edge_callee_property(
     }
     observation.database_opened = true;
 
-    static const char sql[] =
-        "SELECT e.properties, json_valid(e.properties), "
-        "CASE WHEN json_valid(e.properties) "
-        "THEN json_extract(e.properties, '$.callee') END "
-        "FROM edges e "
-        "JOIN nodes src ON src.id=e.source_id AND src.project=e.project "
-        "JOIN nodes tgt ON tgt.id=e.target_id AND tgt.project=e.project "
-        "WHERE e.project=?1 AND e.type=?2 AND src.name=?3 AND tgt.name=?4;";
+    static const char sql[] = "SELECT e.properties, json_valid(e.properties), "
+                              "CASE WHEN json_valid(e.properties) "
+                              "THEN json_extract(e.properties, '$.callee') END "
+                              "FROM edges e "
+                              "JOIN nodes src ON src.id=e.source_id AND src.project=e.project "
+                              "JOIN nodes tgt ON tgt.id=e.target_id AND tgt.project=e.project "
+                              "WHERE e.project=?1 AND e.type=?2 AND src.name=?3 AND tgt.name=?4;";
     sqlite3_stmt *stmt = NULL;
     if (sqlite3_prepare_v2(db, sql, -1, &stmt, NULL) != SQLITE_OK ||
         sqlite3_bind_text(stmt, 1, project, -1, SQLITE_TRANSIENT) != SQLITE_OK ||
@@ -1746,13 +1745,13 @@ TEST(pipeline_call_reference_sequential_parallel_edge_set_parity) {
     long_reference_name[0] = 'l';
     long_reference_name[LONG_REFERENCE_NAME_LEN] = '\0';
     char long_reference_source[1024];
-    int long_reference_source_len = snprintf(
-        long_reference_source, sizeof(long_reference_source),
-        "package parity\n"
-        "func %s() {}\n"
-        "func longPropertiesReferenceAccept(callback func()) {}\n"
-        "func longPropertiesReferenceSite() { longPropertiesReferenceAccept(%s) }\n",
-        long_reference_name, long_reference_name);
+    int long_reference_source_len =
+        snprintf(long_reference_source, sizeof(long_reference_source),
+                 "package parity\n"
+                 "func %s() {}\n"
+                 "func longPropertiesReferenceAccept(callback func()) {}\n"
+                 "func longPropertiesReferenceSite() { longPropertiesReferenceAccept(%s) }\n",
+                 long_reference_name, long_reference_name);
     if (long_reference_source_len <= 0 ||
         (size_t)long_reference_source_len >= sizeof(long_reference_source)) {
         th_rmtree(tmp);
@@ -1940,18 +1939,18 @@ TEST(pipeline_call_reference_sequential_parallel_edge_set_parity) {
                 named_edge_count(sequential_store, sequential_project, "CALLS",
                                  shadow_controls[i].source_name, shadow_controls[i].target_name);
         }
-        sequential_long_reference = named_edge_count(
-            sequential_store, sequential_project, "CALL_REFERENCE", "longPropertiesReferenceSite",
-            long_reference_name);
-        sequential_long_usage = named_edge_count(sequential_store, sequential_project, "USAGE",
-                                                 "longPropertiesReferenceSite",
-                                                 long_reference_name);
-        sequential_long_calls = named_edge_count(sequential_store, sequential_project, "CALLS",
-                                                 "longPropertiesReferenceSite",
-                                                 long_reference_name);
+        sequential_long_reference =
+            named_edge_count(sequential_store, sequential_project, "CALL_REFERENCE",
+                             "longPropertiesReferenceSite", long_reference_name);
+        sequential_long_usage =
+            named_edge_count(sequential_store, sequential_project, "USAGE",
+                             "longPropertiesReferenceSite", long_reference_name);
+        sequential_long_calls =
+            named_edge_count(sequential_store, sequential_project, "CALLS",
+                             "longPropertiesReferenceSite", long_reference_name);
         sequential_long_property = observe_named_edge_callee_property(
-            sequential_db_path, sequential_project, "CALL_REFERENCE",
-            "longPropertiesReferenceSite", long_reference_name, long_reference_name);
+            sequential_db_path, sequential_project, "CALL_REFERENCE", "longPropertiesReferenceSite",
+            long_reference_name, long_reference_name);
         cbm_store_close(sequential_store);
     }
     cbm_pipeline_free(sequential);
@@ -1989,9 +1988,9 @@ TEST(pipeline_call_reference_sequential_parallel_edge_set_parity) {
                 named_edge_count(parallel_store, parallel_project, "CALLS",
                                  shadow_controls[i].source_name, shadow_controls[i].target_name);
         }
-        parallel_long_reference = named_edge_count(
-            parallel_store, parallel_project, "CALL_REFERENCE", "longPropertiesReferenceSite",
-            long_reference_name);
+        parallel_long_reference =
+            named_edge_count(parallel_store, parallel_project, "CALL_REFERENCE",
+                             "longPropertiesReferenceSite", long_reference_name);
         parallel_long_usage = named_edge_count(parallel_store, parallel_project, "USAGE",
                                                "longPropertiesReferenceSite", long_reference_name);
         parallel_long_calls = named_edge_count(parallel_store, parallel_project, "CALLS",
@@ -2339,8 +2338,8 @@ static void closure_probe_repo(const char *tmp) {
 }
 
 /* Fresh full reference build of the same tree into its own DB. */
-static void closure_fresh_full(const char *tmp, const char *db_path, int *out_nodes,
-                               int *out_edges, int *out_ref_edges, const char *project_hint) {
+static void closure_fresh_full(const char *tmp, const char *db_path, int *out_nodes, int *out_edges,
+                               int *out_ref_edges, const char *project_hint) {
     *out_nodes = -1;
     *out_edges = -2;
     *out_ref_edges = -3;
@@ -2357,9 +2356,9 @@ static void closure_fresh_full(const char *tmp, const char *db_path, int *out_no
         if (store) {
             *out_nodes = cbm_store_count_nodes(store, project);
             *out_edges = cbm_store_count_edges(store, project);
-            *out_ref_edges = named_edge_to_file_count(store, project, "CALL_REFERENCE",
-                                                      "closureProbeCaller", "closureProbeHelper",
-                                                      "lib.ts");
+            *out_ref_edges =
+                named_edge_to_file_count(store, project, "CALL_REFERENCE", "closureProbeCaller",
+                                         "closureProbeHelper", "lib.ts");
             cbm_store_close(store);
         }
     }
@@ -2444,8 +2443,8 @@ TEST(pipeline_closure_repair_body_edit_converges_with_fresh_full) {
     ASSERT_NOT_NULL(store);
     repaired_nodes = cbm_store_count_nodes(store, project);
     repaired_edges = cbm_store_count_edges(store, project);
-    repaired_refs = named_edge_to_file_count(store, project, "CALL_REFERENCE",
-                                             "closureProbeCaller", "closureProbeHelper", "lib.ts");
+    repaired_refs = named_edge_to_file_count(store, project, "CALL_REFERENCE", "closureProbeCaller",
+                                             "closureProbeHelper", "lib.ts");
     cbm_store_close(store);
 
     char full_db[512];
@@ -2501,8 +2500,8 @@ TEST(pipeline_closure_repair_removed_def_drops_dependent_edge) {
     int repaired_refs = -1;
     cbm_store_t *store = cbm_store_open_path(db);
     ASSERT_NOT_NULL(store);
-    repaired_refs = named_edge_to_file_count(store, project, "CALL_REFERENCE",
-                                             "closureProbeCaller", "closureProbeHelper", "lib.ts");
+    repaired_refs = named_edge_to_file_count(store, project, "CALL_REFERENCE", "closureProbeCaller",
+                                             "closureProbeHelper", "lib.ts");
     int repaired_nodes = cbm_store_count_nodes(store, project);
     int repaired_edges = cbm_store_count_edges(store, project);
     cbm_store_close(store);
@@ -2745,8 +2744,7 @@ TEST(pipeline_incremental_tsconfig_alias_change_matches_fresh_full) {
      * target_a.ts to target_b.ts. Since alias-config governance landed this
      * runs as a closure repair, and the convergence assertions below now
      * prove that route rather than being satisfied by a full rebuild. */
-    ASSERT_EQ(cbm_pipeline_incremental_test_last_route(),
-              CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR);
+    ASSERT_EQ(cbm_pipeline_incremental_test_last_route(), CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR);
     const char *incremental_project = cbm_pipeline_project_name(incremental);
     cbm_store_t *incremental_store = cbm_store_open_path(incremental_db);
     ASSERT_NOT_NULL(incremental_store);
@@ -2800,6 +2798,87 @@ TEST(pipeline_incremental_tsconfig_alias_change_matches_fresh_full) {
 }
 
 #if defined(CBM_INCREMENTAL_TEST_API) && CBM_INCREMENTAL_TEST_API
+static int read_published_generation(const char *db_path, char *out, size_t out_size) {
+    cbm_store_t *store = cbm_store_open_path_query(db_path);
+    if (!store) {
+        return CBM_STORE_ERR;
+    }
+    int rc = cbm_store_generation(store, out, out_size);
+    cbm_store_close(store);
+    return rc;
+}
+
+static bool split_published_generation(const char *generation, char uid[18],
+                                       unsigned long long *mutation) {
+    if (!generation || strlen(generation) < 19 || generation[0] != 'u' || generation[17] != 'g') {
+        return false;
+    }
+    memcpy(uid, generation, 17);
+    uid[17] = '\0';
+    char *end = NULL;
+    unsigned long long parsed = strtoull(generation + 18, &end, 10);
+    if (!end || end == generation + 18 || *end != '\0') {
+        return false;
+    }
+    *mutation = parsed;
+    return true;
+}
+
+/* Every published database must carry cursor-generation metadata. A complete
+ * replacement gets a fresh database identity; an isolated delta clones the
+ * live database and advances only its mutation counter. */
+TEST(pipeline_publication_stamps_full_and_delta_generations) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_publish_cursor_generation_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    write_temp_file(tmp, "generation.py", "def PublishedGeneration():\n    return 1\n");
+    char db_path[512];
+    snprintf(db_path, sizeof(db_path), "%s/generation.db", tmp);
+
+    cbm_pipeline_incremental_test_reset_faults();
+    cbm_pipeline_t *baseline = cbm_pipeline_new(tmp, db_path, CBM_MODE_FAST);
+    ASSERT_NOT_NULL(baseline);
+    ASSERT_EQ(cbm_pipeline_run(baseline), 0);
+    cbm_pipeline_free(baseline);
+    char first[128];
+    ASSERT_EQ(read_published_generation(db_path, first, sizeof(first)), CBM_STORE_OK);
+
+    cbm_pipeline_incremental_test_reset_faults();
+    cbm_pipeline_t *replacement = cbm_pipeline_new(tmp, db_path, CBM_MODE_FULL);
+    ASSERT_NOT_NULL(replacement);
+    ASSERT_EQ(cbm_pipeline_run(replacement), 0);
+    ASSERT_EQ(cbm_pipeline_incremental_test_last_route(), CBM_INCREMENTAL_ROUTE_FORCED_FULL);
+    cbm_pipeline_free(replacement);
+    char second[128];
+    ASSERT_EQ(read_published_generation(db_path, second, sizeof(second)), CBM_STORE_OK);
+
+    write_temp_file(tmp, "generation.py", "def PublishedGeneration():\n    return 2\n");
+    cbm_pipeline_incremental_test_reset_faults();
+    cbm_pipeline_t *delta = cbm_pipeline_new(tmp, db_path, CBM_MODE_FULL);
+    ASSERT_NOT_NULL(delta);
+    ASSERT_EQ(cbm_pipeline_run(delta), 0);
+    ASSERT_EQ(cbm_pipeline_incremental_test_last_route(), CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR);
+    cbm_pipeline_free(delta);
+    char third[128];
+    ASSERT_EQ(read_published_generation(db_path, third, sizeof(third)), CBM_STORE_OK);
+
+    char first_uid[18];
+    char second_uid[18];
+    char third_uid[18];
+    unsigned long long first_mutation = 0;
+    unsigned long long second_mutation = 0;
+    unsigned long long third_mutation = 0;
+    ASSERT_TRUE(split_published_generation(first, first_uid, &first_mutation));
+    ASSERT_TRUE(split_published_generation(second, second_uid, &second_mutation));
+    ASSERT_TRUE(split_published_generation(third, third_uid, &third_mutation));
+    ASSERT_TRUE(strcmp(first_uid, second_uid) != 0);
+    ASSERT_STR_EQ(second_uid, third_uid);
+    ASSERT_TRUE(third_mutation > second_mutation);
+    th_rmtree(tmp);
+    cbm_pipeline_incremental_test_reset_faults();
+    PASS();
+}
+
 static void observe_named_generation(const char *db_path, const char *project,
                                      const char *before_name, const char *after_name,
                                      int *before_count, int *after_count) {
@@ -2934,8 +3013,8 @@ TEST(pipeline_publication_never_uses_a_predictable_staging_path) {
     static const char canary[] = "canary-must-survive\n";
     char canary_path[PREDICTABLE_CANARIES][640];
     for (int i = 0; i < PREDICTABLE_CANARIES; i++) {
-        snprintf(canary_path[i], sizeof(canary_path[i]), "%s.stage.%ld.%d", db_path,
-                 (long)getpid(), i + 1);
+        snprintf(canary_path[i], sizeof(canary_path[i]), "%s.stage.%ld.%d", db_path, (long)getpid(),
+                 i + 1);
         ASSERT_EQ(th_write_file(canary_path[i], canary), 0);
     }
 
@@ -5821,7 +5900,7 @@ TEST(pipeline_swift_cross_package_import) {
     cbm_edge_t *edges = NULL;
     int ec = 0;
     ASSERT_EQ(cbm_store_find_edges_by_source_type(s, importer.id, "IMPORTS", &edges, &ec),
-             CBM_STORE_OK);
+              CBM_STORE_OK);
 
     bool found_exact_edge = false;
     for (int i = 0; i < ec; i++) {
@@ -9173,17 +9252,16 @@ static const char *pkg_entries_entry_for(const cbm_pkg_entries_t *e, const char
  * above for the full end-to-end proof. */
 
 TEST(pkgmap_swift_targets_registers_module) {
-    static const char src[] =
-        "// swift-tools-version:5.9\n"
-        "import PackageDescription\n"
-        "let package = Package(\n"
-        "    name: \"Core\",\n"
-        "    targets: [.target(name: \"Core\", dependencies: [])]\n"
-        ")\n";
+    static const char src[] = "// swift-tools-version:5.9\n"
+                              "import PackageDescription\n"
+                              "let package = Package(\n"
+                              "    name: \"Core\",\n"
+                              "    targets: [.target(name: \"Core\", dependencies: [])]\n"
+                              ")\n";
     cbm_pkg_entries_t entries;
     cbm_pkg_entries_init(&entries);
-    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src,
-                                   (int)strlen(src), &entries);
+    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src, (int)strlen(src),
+                                   &entries);
     ASSERT_TRUE(ok);
     ASSERT_TRUE(pkg_entries_has_name(&entries, "Core"));
     ASSERT_STR_EQ(pkg_entries_entry_for(&entries, "Core"), "Core/Sources/Core");
@@ -9204,8 +9282,8 @@ TEST(pkgmap_swift_products_do_not_register_alias) {
         ")\n";
     cbm_pkg_entries_t entries;
     cbm_pkg_entries_init(&entries);
-    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src,
-                                   (int)strlen(src), &entries);
+    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src, (int)strlen(src),
+                                   &entries);
     ASSERT_TRUE(ok);
     ASSERT_FALSE(pkg_entries_has_name(&entries, "CoreKit"));
     ASSERT_TRUE(pkg_entries_has_name(&entries, "CoreImpl"));
@@ -9224,15 +9302,14 @@ TEST(pkgmap_swift_products_do_not_register_alias) {
  * fixture in this file happens to follow `name:` with `dependencies:` or a
  * comma, so this specific shape was previously untested and unnoticed. */
 TEST(pkgmap_swift_target_name_immediately_before_close_paren) {
-    static const char src[] =
-        "let package = Package(\n"
-        "    name: \"Core\",\n"
-        "    targets: [.target(name: \"Core\")]\n"
-        ")\n";
+    static const char src[] = "let package = Package(\n"
+                              "    name: \"Core\",\n"
+                              "    targets: [.target(name: \"Core\")]\n"
+                              ")\n";
     cbm_pkg_entries_t entries;
     cbm_pkg_entries_init(&entries);
-    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src,
-                                   (int)strlen(src), &entries);
+    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src, (int)strlen(src),
+                                   &entries);
     ASSERT_TRUE(ok);
     ASSERT_TRUE(pkg_entries_has_name(&entries, "Core"));
     ASSERT_STR_EQ(pkg_entries_entry_for(&entries, "Core"), "Core/Sources/Core");
@@ -9250,8 +9327,8 @@ TEST(pkgmap_swift_target_honors_literal_path) {
         ")\n";
     cbm_pkg_entries_t entries;
     cbm_pkg_entries_init(&entries);
-    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src,
-                                   (int)strlen(src), &entries);
+    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src, (int)strlen(src),
+                                   &entries);
     ASSERT_TRUE(ok);
     ASSERT_TRUE(pkg_entries_has_name(&entries, "Core"));
     ASSERT_STR_EQ(pkg_entries_entry_for(&entries, "Core"), "Core/Vendor/CoreLegacy");
@@ -9265,16 +9342,15 @@ TEST(pkgmap_swift_target_honors_literal_path) {
  * target entirely (fail closed), even though its `name:` is a valid
  * literal. */
 TEST(pkgmap_swift_target_computed_path_fails_closed) {
-    static const char src[] =
-        "let customPath = computePath()\n"
-        "let package = Package(\n"
-        "    name: \"Core\",\n"
-        "    targets: [.target(name: \"Core\", path: customPath)]\n"
-        ")\n";
+    static const char src[] = "let customPath = computePath()\n"
+                              "let package = Package(\n"
+                              "    name: \"Core\",\n"
+                              "    targets: [.target(name: \"Core\", path: customPath)]\n"
+                              ")\n";
     cbm_pkg_entries_t entries;
     cbm_pkg_entries_init(&entries);
-    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src,
-                                   (int)strlen(src), &entries);
+    bool ok = cbm_pkgmap_try_parse("Package.swift", "Core/Package.swift", src, (int)strlen(src),
+                                   &entries);
     ASSERT_TRUE(ok);
     ASSERT_EQ(entries.count, 0);
     cbm_pkg_entries_free(&entries);
@@ -9296,8 +9372,8 @@ TEST(pkgmap_swift_target_in_comment_or_string_not_registered) {
         ")\n";
     cbm_pkg_entries_t entries;
     cbm_pkg_entries_init(&entries);
-    bool ok = cbm_pkgmap_try_parse("Package.swift", "App/Package.swift", src,
-                                   (int)strlen(src), &entries);
+    bool ok =
+        cbm_pkgmap_try_parse("Package.swift", "App/Package.swift", src, (int)strlen(src), &entries);
     ASSERT_TRUE(ok);
     ASSERT_TRUE(pkg_entries_has_name(&entries, "App"));
     ASSERT_FALSE(pkg_entries_has_name(&entries, "Decoy"));
@@ -9326,8 +9402,8 @@ TEST(pkgmap_swift_dependencies_do_not_leak_entries) {
         ")\n";
     cbm_pkg_entries_t entries;
     cbm_pkg_entries_init(&entries);
-    bool ok = cbm_pkgmap_try_parse("Package.swift", "App/Package.swift", src,
-                                   (int)strlen(src), &entries);
+    bool ok =
+        cbm_pkgmap_try_parse("Package.swift", "App/Package.swift", src, (int)strlen(src), &entries);
     ASSERT_TRUE(ok);
     ASSERT_TRUE(pkg_entries_has_name(&entries, "App"));
     ASSERT_FALSE(pkg_entries_has_name(&entries, "Core"));
@@ -9342,18 +9418,17 @@ TEST(pkgmap_swift_dependencies_do_not_leak_entries) {
  * (Utils/UtilsPkg) name OTHER modules, not this manifest's own
  * products/targets, so neither mints an entry. */
 TEST(pkgmap_swift_target_name_dependency_does_not_leak_entry) {
-    static const char src[] =
-        "let package = Package(\n"
-        "    name: \"App\",\n"
-        "    targets: [.target(name: \"App\", dependencies: [\n"
-        "        \"Core\",\n"
-        "        .product(name: \"Utils\", package: \"UtilsPkg\")\n"
-        "    ])]\n"
-        ")\n";
+    static const char src[] = "let package = Package(\n"
+                              "    name: \"App\",\n"
+                              "    targets: [.target(name: \"App\", dependencies: [\n"
+                              "        \"Core\",\n"
+                              "        .product(name: \"Utils\", package: \"UtilsPkg\")\n"
+                              "    ])]\n"
+                              ")\n";
     cbm_pkg_entries_t entries;
     cbm_pkg_entries_init(&entries);
-    bool ok = cbm_pkgmap_try_parse("Package.swift", "App/Package.swift", src,
-                                   (int)strlen(src), &entries);
+    bool ok =
+        cbm_pkgmap_try_parse("Package.swift", "App/Package.swift", src, (int)strlen(src), &entries);
     ASSERT_TRUE(ok);
     ASSERT_TRUE(pkg_entries_has_name(&entries, "App"));
     ASSERT_FALSE(pkg_entries_has_name(&entries, "Core"));
@@ -11910,6 +11985,7 @@ SUITE(pipeline_semantic_manifest_repro) {
     RUN_TEST(pipeline_closure_repair_budget_declines_to_full);
     RUN_TEST(pipeline_incremental_tsconfig_alias_change_matches_fresh_full);
 #if defined(CBM_INCREMENTAL_TEST_API) && CBM_INCREMENTAL_TEST_API
+    RUN_TEST(pipeline_publication_stamps_full_and_delta_generations);
     RUN_TEST(pipeline_git_context_change_forces_full_and_refreshes_branch);
     RUN_TEST(pipeline_global_extension_config_change_forces_full);
     RUN_TEST(pipeline_publication_never_uses_a_predictable_staging_path);
diff --git a/tests/test_store_pragmas.c b/tests/test_store_pragmas.c
index 0d093589c..757d46363 100644
--- a/tests/test_store_pragmas.c
+++ b/tests/test_store_pragmas.c
@@ -143,6 +143,35 @@ TEST(store_generation_tracks_mutations) {
     PASS();
 }
 
+/* Existing store_meta is authoritative: a partially-written or malformed
+ * table is corruption, not a legacy database. Generation reads and the
+ * project-upsert mutation choke point must both fail closed, and a failed
+ * generation advance must not leave the project row committed. */
+TEST(store_generation_rejects_malformed_metadata_atomically) {
+    cbm_store_t *s = cbm_store_open_memory();
+    ASSERT_NOT_NULL(s);
+    ASSERT_EQ(cbm_store_exec(s, "CREATE TABLE store_meta (k TEXT PRIMARY KEY, v TEXT);"
+                                "INSERT INTO store_meta VALUES('db_uid','0123456789abcdef');"),
+              CBM_STORE_OK);
+
+    char generation[128] = {0};
+    ASSERT_EQ(cbm_store_generation(s, generation, sizeof(generation)), CBM_STORE_ERR);
+    ASSERT_EQ(cbm_store_upsert_project(s, "must-not-commit", "/tmp/must-not-commit"),
+              CBM_STORE_ERR);
+    cbm_project_t project = {0};
+    ASSERT_EQ(cbm_store_get_project(s, "must-not-commit", &project), CBM_STORE_NOT_FOUND);
+
+    ASSERT_EQ(cbm_store_exec(s, "INSERT INTO store_meta VALUES('mutation_gen','not-a-number');"),
+              CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_generation(s, generation, sizeof(generation)), CBM_STORE_ERR);
+    ASSERT_EQ(cbm_store_exec(s, "UPDATE store_meta SET v=CAST(X'31006a756e6b' AS TEXT) "
+                                "WHERE k='mutation_gen';"),
+              CBM_STORE_OK);
+    ASSERT_EQ(cbm_store_generation(s, generation, sizeof(generation)), CBM_STORE_ERR);
+    cbm_store_close(s);
+    PASS();
+}
+
 /* #896: a row-scan that dies mid-stream (SQLITE_CORRUPT) must surface a
  * loud store error, not masquerade as a clean end of results. Counts are
  * answered from covering indexes (still correct) while row fetches die at
@@ -236,6 +265,7 @@ TEST(corrupt_page_scan_returns_error_not_truncation) {
 SUITE(store_pragmas) {
     RUN_TEST(journal_size_limit_bounds_wal_issue1083);
     RUN_TEST(store_generation_tracks_mutations);
+    RUN_TEST(store_generation_rejects_malformed_metadata_atomically);
     RUN_TEST(corrupt_page_scan_returns_error_not_truncation);
     RUN_TEST(mmap_size_default_when_unset);
     RUN_TEST(mmap_size_zero_disables_mmap);
diff --git a/tests/test_worker_error_response.sh b/tests/test_worker_error_response.sh
index 5a28fb7da..64d8ecc84 100755
--- a/tests/test_worker_error_response.sh
+++ b/tests/test_worker_error_response.sh
@@ -36,10 +36,17 @@ if [[ ! "${BUILD_FINGERPRINT}" =~ ^[0-9a-f]{64}$ ]]; then
 fi
 
 tmpdir="$(mktemp -d)"
+case "$(uname -s)" in
+  Darwin) runtime_root="/private/tmp" ;;
+  *) runtime_root="/tmp" ;;
+esac
+runtime_parent="$(mktemp -d "${runtime_root}/cbm-worker-error-runtime.XXXXXX")"
 cleanup() {
+  CBM_TEST_DAEMON_RUNTIME_PARENT="${runtime_parent}" \
   CBM_CACHE_DIR="${tmpdir}/cache-supervisor" \
     "${BINARY}" daemon stop >/dev/null 2>&1 || true
   rm -rf "${tmpdir}"
+  rm -rf "${runtime_parent}"
 }
 trap cleanup EXIT
 
@@ -47,7 +54,8 @@ missing="${tmpdir}/repository-does-not-exist"
 response="${tmpdir}/worker.response"
 args="{\"repo_path\":\"${missing}\",\"mode\":\"fast\"}"
 
-if ! CBM_CACHE_DIR="${tmpdir}/cache-worker" \
+if ! CBM_TEST_DAEMON_RUNTIME_PARENT="${runtime_parent}" \
+  CBM_CACHE_DIR="${tmpdir}/cache-worker" \
   "${BINARY}" cli --index-worker \
   --index-worker-build "${BUILD_FINGERPRINT}" \
   index_repository "${args}" \
@@ -64,7 +72,8 @@ if [[ ! -s "${response}" ]] || ! grep -q 'Pipeline failed' "${response}"; then
 fi
 
 set +e
-CBM_CACHE_DIR="${tmpdir}/cache-supervisor" \
+CBM_TEST_DAEMON_RUNTIME_PARENT="${runtime_parent}" \
+  CBM_CACHE_DIR="${tmpdir}/cache-supervisor" \
   "${BINARY}" cli index_repository --repo-path "${missing}" --mode fast \
   >"${tmpdir}/supervisor.out" 2>"${tmpdir}/supervisor.err"
 cli_rc=$?
diff --git a/tests/test_worker_watchdog.sh b/tests/test_worker_watchdog.sh
index 01ce360a6..eb8ed0244 100755
--- a/tests/test_worker_watchdog.sh
+++ b/tests/test_worker_watchdog.sh
@@ -66,6 +66,11 @@ if [[ ! "${BUILD_FINGERPRINT}" =~ ^[0-9a-f]{64}$ ]]; then
 fi
 
 tmpdir="$(mktemp -d)"
+case "$(uname -s)" in
+  Darwin) runtime_root="/private/tmp" ;;
+  *) runtime_root="/tmp" ;;
+esac
+runtime_parent="$(mktemp -d "${runtime_root}/cbm-worker-watchdog-runtime.XXXXXX")"
 wrapper_pid=""
 cleanup() {
   if [[ -s "${tmpdir}/child.pid" ]]; then
@@ -80,6 +85,7 @@ cleanup() {
   fi
   [[ -n "${wrapper_pid}" ]] && kill -9 "${wrapper_pid}" 2>/dev/null || true
   rm -rf "${tmpdir}"
+  rm -rf "${runtime_parent}"
 }
 trap cleanup EXIT
 
@@ -107,6 +113,7 @@ chmod +x "${tmpdir}/wrapper.sh"
 
 CBM_BINARY="${BINARY}" BUILD_FINGERPRINT="${BUILD_FINGERPRINT}" TMPDIR_PATH="${tmpdir}" \
   ARGS_JSON="{\"repo_path\":\"${tmpdir}/repo\"}" \
+  CBM_TEST_DAEMON_RUNTIME_PARENT="${runtime_parent}" \
   CBM_TEST_HANG_ON=hang_me \
   CBM_TEST_WORKER_DESCENDANT_PID_FILE="${tmpdir}/descendant.pid" \
   "${tmpdir}/wrapper.sh" &
diff --git a/tests/windows/test_daemon_lifecycle.py b/tests/windows/test_daemon_lifecycle.py
index 55ad85e66..330b52f3e 100644
--- a/tests/windows/test_daemon_lifecycle.py
+++ b/tests/windows/test_daemon_lifecycle.py
@@ -6,7 +6,8 @@
 * ``daemon start`` launches a PERMANENT daemon: it reports a pid, and the
   daemon survives its clients (a one-shot ``cli`` command recycles it without
   printing the cold-start hint, and the daemon is still active afterwards).
-* A cold one-shot ``cli`` command (no daemon) prints the startup-tax hint.
+* A cold one-shot ``cli`` command is quiet by default; ``cli --verbose`` opts
+  into the startup-tax hint.
 * ``daemon stop`` on an idle daemon stops it; a second ``stop`` is idempotent.
 
 Every path carries a kill-by-pid backstop so a stuck daemon can never hang the
@@ -66,11 +67,23 @@ def main():
 
         cold = run_cli(binary, cache, ["cli", "list_projects", "{}"])
         cold_text = output_text(cold)
-        if cold.returncode != 0 or "daemon start" not in cold_text:
-            print("RED: a cold one-shot cli command should succeed and hint at "
-                  "`daemon start`:\n%s" % cold_text[:400])
+        if cold.returncode != 0 or "daemon start" in cold_text:
+            print("RED: a cold one-shot cli command should succeed without default "
+                  "startup chatter:\n%s" % cold_text[:400])
             return 1
-        print("PASS: cold cli one-shot succeeded and printed the startup-tax hint")
+        print("PASS: cold cli one-shot succeeded quietly")
+
+        # Use an isolated rendezvous namespace to guarantee a cold verbose call.
+        verbose_cache = os.path.join(work, "cache-verbose")
+        os.makedirs(verbose_cache, exist_ok=True)
+        verbose = run_cli(binary, verbose_cache,
+                          ["cli", "--verbose", "list_projects", "{}"])
+        verbose_text = output_text(verbose)
+        if verbose.returncode != 0 or "daemon start" not in verbose_text:
+            print("RED: `cli --verbose` should expose the cold-start hint:\n%s"
+                  % verbose_text[:400])
+            return 1
+        print("PASS: verbose cold cli exposed the startup-tax hint")
 
         start = run_cli(binary, cache, ["daemon", "start"])
         start_text = output_text(start)
diff --git a/tests/windows/test_daemon_stability.py b/tests/windows/test_daemon_stability.py
index dbe496fef..76abea014 100644
--- a/tests/windows/test_daemon_stability.py
+++ b/tests/windows/test_daemon_stability.py
@@ -270,9 +270,9 @@ def section_crash_recovery(binary, work):
                   "(`daemon status` kept reporting it)" % daemon_pid)
             return False
         cold = run_cli(binary, cache, ["cli", "list_projects", "{}"], timeout=90)
-        if cold.returncode != 0 or "daemon start" not in out_text(cold):
-            print("RED: a cold one-shot after the daemon crash should succeed with the "
-                  "startup-tax hint:\n%s" % out_text(cold)[:400])
+        if cold.returncode != 0 or "daemon start" in out_text(cold):
+            print("RED: a cold one-shot after the daemon crash should succeed without "
+                  "default startup chatter:\n%s" % out_text(cold)[:400])
             return False
         restart = run_cli(binary, cache, ["daemon", "start"], timeout=60)
         second_pid = pid_from(out_text(restart))