From 15bef512b4f91c3fca65c8dad1d9e5c26ef764c9 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Wed, 12 Aug 2026 20:04:46 +0200
Subject: [PATCH 01/26] feat(mcp): make tool output lean and lossless

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md                                     |    9 +-
 .../src/components/NodeDetailPanel.test.tsx   |    6 +
 graph-ui/src/components/NodeDetailPanel.tsx   |    2 +
 graph-ui/src/components/StatsTab.test.tsx     |    7 +-
 graph-ui/src/hooks/useProjects.test.tsx       |   86 +
 graph-ui/src/hooks/useProjects.ts             |   71 +-
 graph-ui/tsconfig.tsbuildinfo                 |    2 +-
 scripts/smoke-test.sh                         |   14 +-
 src/cli/hook_augment.c                        |  170 +-
 src/cli/progress_sink.c                       |   41 +
 src/cypher/cypher.c                           |  115 +-
 src/cypher/cypher.h                           |    4 +
 src/foundation/log.c                          |    2 +-
 src/foundation/log.h                          |    2 +-
 src/main.c                                    |   38 +-
 src/mcp/compact_out.c                         |  644 ++
 src/mcp/compact_out.h                         |   23 +
 src/mcp/mcp.c                                 | 5721 +++++++++++++----
 src/mcp/mcp_internal.h                        |    9 +
 src/store/store.c                             |   91 +-
 src/store/store.h                             |   10 +
 src/ui/http_server.c                          |    3 +-
 tests/scale_contract.sh                       |    9 +-
 tests/test_cli.c                              |  153 +
 tests/test_cypher.c                           |  173 +-
 tests/test_daemon_runtime.c                   |    3 +
 tests/test_httpd.c                            |   29 +-
 tests/test_incremental.c                      |   20 +-
 tests/test_index_resilience.c                 |    7 +-
 tests/test_log.c                              |   41 +-
 tests/test_mcp.c                              | 3558 +++++++++-
 tests/windows/test_daemon_lifecycle.py        |   23 +-
 tests/windows/test_daemon_stability.py        |    6 +-
 33 files changed, 9436 insertions(+), 1656 deletions(-)
 create mode 100644 graph-ui/src/hooks/useProjects.test.tsx

diff --git a/README.md b/README.md
index 87cf17920..63c83703b 100644
--- a/README.md
+++ b/README.md
@@ -576,7 +576,11 @@ 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. 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 that table is at least 15% and 64 bytes smaller. 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. These are deterministic model-neutral byte savings that normally reduce tokens; 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` additionally exposes `raw_limit`, `directory_limit`, `match_limit`, and `source_max_lines`; its default retains eight match locations per graph result and reports the exact `matches_omitted` remainder. `detect_changes` pages changed files, impacted symbols, and module summaries independently.
 
 Use `cli <tool> --help` to see the flags generated from that tool's input schema:
 
@@ -591,7 +595,8 @@ 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'
+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.
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/graph-ui/tsconfig.tsbuildinfo b/graph-ui/tsconfig.tsbuildinfo
index 0da71675b..5f1f5e115 100644
--- a/graph-ui/tsconfig.tsbuildinfo
+++ b/graph-ui/tsconfig.tsbuildinfo
@@ -1 +1 @@
-{"root":["./src/app.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/rpc.ts","./src/components/controltab.tsx","./src/components/edgelines.tsx","./src/components/errorboundary.tsx","./src/components/filterpanel.tsx","./src/components/graphscene.test.ts","./src/components/graphscene.tsx","./src/components/graphtab.test.ts","./src/components/graphtab.tsx","./src/components/nodecloud.tsx","./src/components/nodedetailpanel.tsx","./src/components/nodelabels.tsx","./src/components/nodetooltip.tsx","./src/components/projectcard.tsx","./src/components/resizehandle.tsx","./src/components/sidebar.tsx","./src/components/statstab.test.tsx","./src/components/statstab.tsx","./src/components/tabbar.tsx","./src/components/ui/badge.tsx","./src/components/ui/button.tsx","./src/components/ui/card.tsx","./src/components/ui/checkbox.tsx","./src/components/ui/input.tsx","./src/components/ui/scroll-area.tsx","./src/components/ui/separator.tsx","./src/hooks/usegraphdata.test.ts","./src/hooks/usegraphdata.ts","./src/hooks/useprojects.ts","./src/lib/colors.ts","./src/lib/i18n.test.ts","./src/lib/i18n.ts","./src/lib/types.ts","./src/lib/utils.ts"],"version":"5.9.3"}
\ No newline at end of file
+{"root":["./src/app.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/rpc.ts","./src/components/controltab.tsx","./src/components/displaysettingsmenu.tsx","./src/components/edgelines.tsx","./src/components/errorboundary.tsx","./src/components/filterpanel.tsx","./src/components/graphloader.tsx","./src/components/graphscene.test.ts","./src/components/graphscene.tsx","./src/components/graphtab.deadcode.test.tsx","./src/components/graphtab.filters.test.tsx","./src/components/graphtab.test.ts","./src/components/graphtab.tsx","./src/components/missedcallout.tsx","./src/components/nodecloud.tsx","./src/components/nodedetailpanel.test.tsx","./src/components/nodedetailpanel.tsx","./src/components/nodelabels.tsx","./src/components/nodetooltip.tsx","./src/components/projectcard.tsx","./src/components/resizehandle.tsx","./src/components/sidebar.tsx","./src/components/statstab.test.tsx","./src/components/statstab.tsx","./src/components/tabbar.tsx","./src/components/ui/badge.tsx","./src/components/ui/button.tsx","./src/components/ui/card.tsx","./src/components/ui/checkbox.tsx","./src/components/ui/input.tsx","./src/components/ui/scroll-area.tsx","./src/components/ui/separator.tsx","./src/hooks/usegraphdata.test.ts","./src/hooks/usegraphdata.ts","./src/hooks/useprojects.test.tsx","./src/hooks/useprojects.ts","./src/lib/colors.ts","./src/lib/density.test.ts","./src/lib/density.ts","./src/lib/i18n.test.ts","./src/lib/i18n.ts","./src/lib/types.ts","./src/lib/utils.ts"],"version":"5.9.3"}
\ No newline at end of file
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/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..23868f2b2 100644
--- a/src/cli/progress_sink.c
+++ b/src/cli/progress_sink.c
@@ -31,6 +31,8 @@ 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 cbm_mutex_t s_sink_mutex;
 static atomic_int s_sink_mutex_state = ATOMIC_VAR_INIT(LOCK_UNINITIALIZED);
 
@@ -184,6 +186,13 @@ 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_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 +206,10 @@ 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;
+    }
     cbm_mutex_unlock(&s_sink_mutex);
 }
 
@@ -338,6 +351,19 @@ 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, but keep routine worker chatter out of the human progress
+ * view. Logger callbacks do not include a trailing newline. */
+static void passthrough_failure(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 +371,21 @@ 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_failure(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);
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/log.c b/src/foundation/log.c
index 5b0b86007..56116109d 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
diff --git a/src/foundation/log.h b/src/foundation/log.h
index baad71d14..b8ee9bcc7 100644
--- a/src/foundation/log.h
+++ b/src/foundation/log.h
@@ -44,7 +44,7 @@ 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). */
+/* Set minimum log level (default: WARN; INFO is opt-in). */
 void cbm_log_set_level(CBMLogLevel level);
 
 /* Get current log level. */
diff --git a/src/main.c b/src/main.c
index 574002b6a..727f01b44 100644
--- a/src/main.c
+++ b/src/main.c
@@ -6,6 +6,7 @@
  *   cli <tool> <json>  Run a single tool call and print result
  *   --version       Print version and exit
  *   --help          Print usage and exit
+ *   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 +534,11 @@ 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 [--progress] [--verbose] [--json] <tool_name> [json_args]\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":...}
@@ -581,6 +586,24 @@ static bool cli_strip_flag(int *argc, char **argv, const char *flag) {
     return false;
 }
 
+/* Outer CLI flags precede the tool name. Keep this distinct from
+ * cli_strip_flag(): several MCP tools have their own `verbose` input, so
+ * `cli index_status --verbose` must remain a tool argument while
+ * `cli --verbose index_status` configures process logging. */
+static bool cli_strip_outer_flag(int *argc, char **argv, const char *flag) {
+    for (int i = 0; i < *argc && argv[i] && argv[i][0] == '-'; i++) {
+        if (strcmp(argv[i], flag) != 0) {
+            continue;
+        }
+        for (int j = i; j < *argc - SKIP_ONE; j++) {
+            argv[j] = argv[j + SKIP_ONE];
+        }
+        (*argc)--;
+        return true;
+    }
+    return false;
+}
+
 /* Strip a flag AND its following value from argv, returning the value (a pointer
  * into the original argv strings, valid for the process lifetime) or NULL if the
  * flag is absent. */
@@ -663,6 +686,10 @@ static char *main_local_cli_daemon_execute(const char *tool_name, const char *ar
 
 static int run_cli(int argc, char **argv, cbm_project_lock_manager_t *project_locks,
                    main_local_maintenance_context_t *maintenance_context) {
+    bool verbose_requested = cli_strip_outer_flag(&argc, argv, "--verbose");
+    if (verbose_requested && cbm_log_get_level() > CBM_LOG_INFO) {
+        cbm_log_set_level(CBM_LOG_INFO);
+    }
     if (argc == 1 && argv && (strcmp(argv[0], "--help") == 0 || strcmp(argv[0], "-h") == 0)) {
         (void)fputs(CLI_USAGE, stdout);
         return 0;
@@ -890,7 +917,7 @@ 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 [--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");
@@ -1552,9 +1579,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];
diff --git a/src/mcp/compact_out.c b/src/mcp/compact_out.c
index 2d8bef364..c18c474fc 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 };
 
@@ -296,3 +297,646 @@ 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_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;
+
+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;
+}
+
+static bool tree_prefix_matches(const char *value, const tree_prefix_candidate_t *candidate) {
+    return value && !needs_quotes(value) && strlen(value) >= candidate->len &&
+           memcmp(value, candidate->text, candidate->len) == 0;
+}
+
+static int tree_prefix_choice(const char *value, const tree_prefix_candidate_t *candidates,
+                              int selected_count, bool active_only) {
+    int choice = -1;
+    size_t longest = 0;
+    for (int i = 0; i < selected_count; i++) {
+        if ((active_only && !candidates[i].active) || !tree_prefix_matches(value, &candidates[i])) {
+            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;
+    }
+
+    /* 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++) {
+        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) &&
+                tree_prefix_matches(cells[cell], &candidates[i])) {
+                candidates[i].uses++;
+            }
+        }
+        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;
+        }
+    }
+    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;
+    }
+
+    int active_count = 0;
+    for (int i = 0; i < selected_count; i++) {
+        /* Recompute the exclusive longest-prefix assignment without another
+         * allocation; shorter overlapping candidates may become unused. */
+        size_t exclusive_uses = 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) &&
+                tree_prefix_choice(cells[cell], candidates, selected_count, false) == i) {
+                exclusive_uses++;
+            }
+        }
+        candidates[i].active = exclusive_uses >= 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;
+    }
+
+    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);
+        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 = tree_column_is_prefixable(string_cols, prefix_cols, col)
+                             ? tree_prefix_choice(value, candidates, selected_count, true)
+                             : -1;
+            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;
+        use_compact =
+            saving >= TREE_PREFIX_MIN_SAVING && saving * 100 >= plain_len * TREE_PREFIX_MIN_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);
+    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, int depth) {
+    size_t len = strlen(text);
+    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");
+
+    const char *line = text;
+    for (;;) {
+        const char *newline = strchr(line, '\n');
+        const char *end = newline ? newline : line + strlen(line);
+        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);
+                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 = newline + 1;
+        if (*line == '\0') {
+            break;
+        }
+    }
+}
+
+static void json_tree_scalar(cbm_sb_t *sb, yyjson_val *value) {
+    if (yyjson_is_str(value)) {
+        append_value(sb, yyjson_get_str(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_get(item, yyjson_get_str(key))) {
+                return false;
+            }
+        }
+    }
+    *first_out = first;
+    return true;
+}
+
+static void json_tree_value(cbm_sb_t *sb, const char *key_name, yyjson_val *value, int depth);
+
+static void json_tree_object_table(cbm_sb_t *sb, const char *key_name, yyjson_val *array,
+                                   yyjson_val *first, int depth) {
+    if (!sb || !key_name || !array || !first) {
+        return;
+    }
+    json_tree_indent(sb, depth);
+    cbm_sb_append(sb, key_name);
+    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);
+        cbm_sb_append(sb, yyjson_get_str(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_get(row, yyjson_get_str(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, 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, array, first, depth);
+        return;
+    }
+
+    json_tree_indent(sb, depth);
+    cbm_sb_append(sb, key_name);
+    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), field_value, depth + 2);
+            }
+        } else if (yyjson_is_arr(item)) {
+            json_tree_value(sb, "-", 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, yyjson_val *value, int depth) {
+    if (depth >= JSON_TREE_MAX_DEPTH) {
+        json_tree_indent(sb, depth);
+        cbm_sb_append(sb, key_name);
+        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);
+        cbm_sb_append(sb, key_name);
+        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), child, depth + 1);
+        }
+    } else if (yyjson_is_arr(value)) {
+        json_tree_array(sb, key_name, value, depth);
+    } else if (yyjson_is_str(value) &&
+               (strchr(yyjson_get_str(value), '\n') || strchr(yyjson_get_str(value), '\r'))) {
+        json_tree_indent(sb, depth);
+        cbm_sb_append(sb, key_name);
+        cbm_sb_append(sb, ": ");
+        json_tree_block_string(sb, yyjson_get_str(value), depth);
+    } else {
+        json_tree_indent(sb, depth);
+        cbm_sb_append(sb, key_name);
+        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), value, 0);
+        }
+    } else if (yyjson_is_arr(root)) {
+        json_tree_array(&sb, "items", 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..6706e2086 100644
--- a/src/mcp/compact_out.h
+++ b/src/mcp/compact_out.h
@@ -51,4 +51,27 @@ 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 it saves at
+ * least 15% and 64 bytes. */
+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..c0630d34b 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
@@ -374,117 +379,51 @@ typedef struct {
 
 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 a repository. full/moderate add semantic edges; fast omits them; "
+     "cross-repo-intelligence links indexed services. Results summarize 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 files+semantic; moderate: "
+     "filtered+semantic; "
+     "fast: filtered without semantic; 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.\"},"
+     "\"Project-name override; Non-ASCII bytes are encoded and 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: BM25 query, regex name/qn, or vector semantic_query. Regex rows keep "
+     "qn/file/lines and in/out over CALLS, USAGE, CALL_REFERENCE, INHERITS, IMPLEMENTS. "
+     "Defaults: the smaller lossless direct/grouped tree, limit 50, ~3200 tokens (4x byte cap). "
+     "Page with offset; detail=ids is qn-only.",
      "{\"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\"}},\"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\"]},"
+     "\"fields\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},"
+     "\"detail\":{\"type\":\"string\",\"enum\":[\"ids\",\"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.",
+     "Run read-only Cypher for multi-hop patterns, aggregation, complexity, or cross-service "
+     "analysis. Defaults to 200 visible rows and reports exact or lower-bound totals plus "
+     "truncation. Use max_rows or Cypher SKIP/LIMIT to continue. graph=missed queries flagged "
+     "coverage files; absence there is not proof of completeness. Call get_graph_schema with "
+     "diagnostics=full to discover queryable property names.",
      "{\"type\":\"object\",\"properties\":{\"query\":{\"type\":\"string\",\"description\":\"Cypher "
      "query\"},\"project\":{\"type\":\"string\"},"
      "\"graph\":{\"type\":\"string\",\"enum\":[\"code\",\"missed\"],\"default\":\"code\","
@@ -492,78 +431,85 @@ static const tool_def_t TOOLS[] = {
      "missed graph (only files not fully indexed, laid out as their file structure).\"},"
      "\"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 row budget (default 200; max 99998). Zero preserves the legacy maximum "
+     "window. This never changes query evaluation.\",\"minimum\":0,\"default\":200},"
+     "\"offset\":{\"type\":\"integer\",\"minimum\":0,\"default\":0,"
+     "\"description\":\"Skip materialized result rows for response paging; unlike Cypher "
+     "SKIP, this does not change query evaluation.\"},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"minimum\":128,\"maximum\":1000000,"
+     "\"description\":\"Approximate token sizing; deterministic ceiling is 4 UTF-8 bytes per "
+     "requested token. Rows are omitted only whole.\"},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\","
+     "\"description\":\"tree may encode repeated prefixes with a local @N+suffix directory; "
+     "json keeps 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 callers/callees, data flow, or cross-service paths. Defaults exclude tests and "
+     "resolver evidence. Rows retain qn/hop; totals, relations, and continuations are explicit.",
      "{\"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\":\"Visible rows per page; a gte relation flags the 5000-node engine "
+     "ceiling.\"},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"default\":3200,\"minimum\":128,"
+     "\"maximum\":1000000,\"description\":\"Approximate token sizing; deterministic ceiling "
+     "is 4 UTF-8 bytes per requested token. Optional evidence/args yield before nearest graph "
+     "rows.\"},"
+     "\"cursor\":{\"type\":\"string\",\"description\":\"Pass tree next or JSON next_cursor back "
+     "with traversal args unchanged; max_output_tokens may be raised.\"},"
+     "\"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-boundary 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 the smaller complete direct/grouped shape; json preserves "
+     "a stable grouped table model.\"},"
      "\"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.",
+     "Read a symbol found by search_graph. auto returns bounded source, but outlines large "
+     "containers; full restores up to 500 lines; outline and source pages carry continuations. "
+     "coverage_note marks partial indexing.",
      "{\"type\":\"object\",\"properties\":{\"qualified_name\":{\"type\":\"string\",\"description\":"
-     "\"Full qualified_name from search_graph, or short function name\"},\"project\":{"
+     "\"Qualified name from search_graph, 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\":\"Approximate token sizing for auto/outline "
+     "(default 2500); deterministic ceiling is 4 UTF-8 bytes per requested token. Source is "
+     "reduced only at whole-line boundaries. Explicit full is uncapped unless this is 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 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 a compact architecture overview: counts, languages, packages, and entry points. "
+     "Request aspects for structure, dependencies, routes, hotspots, boundaries, layers, "
+     "clusters, cycles, or file tree; path scopes to 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. "
@@ -573,118 +519,117 @@ static const tool_def_t TOOLS[] = {
      "\"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).\"}},"
+     "except file_tree; omit = languages/packages/entry_points. cycles is always 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.",
+     "Graph-augmented text search. compact (default) returns ranked symbols; full adds bounded "
+     "source; files returns paths. Narrow filters or raise limit when has_more.",
      "{\"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\",\"description\":\"compact "
+     "rows; full bounded source; files paths.\"},"
+     "\"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\"]}"},
+     "\"default\":10,\"minimum\":1,\"maximum\":500,\"description\":\"Ranked graph rows.\"},"
+     "\"raw_limit\":{\"type\":\"integer\",\"default\":5,\"minimum\":0,\"maximum\":100,"
+     "\"description\":\"Unclassified grep rows; set 0 to omit.\"},"
+     "\"directory_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":0,"
+     "\"maximum\":64,\"description\":\"Directory summary rows; set 0 to omit.\"},"
+     "\"match_limit\":{\"type\":\"integer\",\"default\":8,\"minimum\":1,"
+     "\"maximum\":500,\"description\":\"Locations per row; exact remainder in matches_omitted.\"},"
+     "\"source_max_lines\":{\"type\":\"integer\",\"default\":20,\"minimum\":1,"
+     "\"maximum\":200,\"description\":\"Per-result source window in full mode.\"},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"minimum\":128,\"maximum\":1000000,"
+     "\"description\":\"Approximate sizing; hard cap 4 UTF-8 bytes/token. Diagnostics yield "
+     "before graph rows.\"},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
+     "\"required\":[\"pattern\",\"project\"]}"},
 
-    {"list_projects", "List projects", "List all indexed projects",
-     "{\"type\":\"object\",\"properties\":{}}"},
+    {"list_projects", "List projects",
+     "List indexed projects with stable paging. Identity is "
+     "the lean default; request stats for 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 mode: omit counts, size, and branch.\"}}}"},
     {"delete_project", "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.",
+     "Get project readiness, counts, root, and coverage-gap counts. diagnostics=summary/full adds "
+     "sample/file rows; verbose adds Git-path diagnostics. Coverage is best-effort, not proof of "
+     "completeness; use check_index_coverage for cited paths.",
      "{\"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\":["
+     "lives — omitted by default to keep the status lean.\"},"
+     "\"diagnostics\":{\"type\":\"string\",\"enum\":[\"none\",\"summary\",\"full\"],"
+     "\"default\":\"none\",\"description\":\"Coverage rows: counts only, 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.",
+     "Best-effort coverage/freshness for exact paths or scopes. Paths and scopes page separately; "
+     "diagnostics=full adds raw detail. A clean result 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.",
+     "Map a Git diff to changed files and transitive graph impact. Sections page independently; "
+     "totals and continuations stay explicit.",
      "{\"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\"]},"
      "\"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},"
+     "\"changed_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":0,\"maximum\":5000},"
+     "\"changed_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"module_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":0,\"maximum\":256},"
+     "\"module_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"default\":3200,\"minimum\":128,"
+     "\"maximum\":1000000,\"description\":\"Approximate token sizing; deterministic ceiling "
+     "is 4 UTF-8 bytes per requested 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", "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 heading rows; get returns content; update replaces all; "
+     "sections is the legacy heading list.\"},\"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", "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\":"
@@ -1231,33 +1176,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 +1467,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
  * ══════════════════════════════════════════════════════════════════ */
@@ -2494,12 +2452,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 +2513,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 +2611,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 +2623,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 +2649,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 +2847,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 +2877,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 +2989,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 +3043,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,11 +3174,167 @@ static char *bm25_file_pattern_like(const char *file_pattern) {
     return like;
 }
 
+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;
+    }
+    for (int i = 0; i < count; i++) {
+        free(rows[i].qualified_name);
+        free(rows[i].label);
+        free(rows[i].file_path);
+    }
+    free(rows);
+}
+
+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 toon) {
+                         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;
@@ -2935,7 +3370,7 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
         "FROM ("
         "    SELECT rowid, bm25(nodes_fts) AS base_rank"
         "    FROM nodes_fts WHERE nodes_fts MATCH ?1"
-        "    ORDER BY base_rank LIMIT ?5"
+        "    ORDER BY base_rank, rowid LIMIT ?5"
         ") fts "
         "JOIN nodes n ON n.id = fts.rowid "
         "WHERE n.project = ?2 "
@@ -2970,7 +3405,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 +3432,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 +3520,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 +3529,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);
@@ -3168,26 +3582,10 @@ 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);
-    }
-    return type_error;
-}
-
 /* ── 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 +3653,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 +3662,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 +3677,168 @@ 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;
+
+static bool sg_page_has_more(int total, int offset, int returned) {
+    return total > 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 has_more = continuation_supported && sg_page_has_more(total, offset, plan->returned);
+    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_higher_budget", true);
+    }
+    bool truncated = has_more || plan->budget_hit;
+    cbm_tree_scalar_bool(sb, "truncated", truncated);
+    if (truncated) {
+        cbm_tree_scalar_str(sb, "truncation_reason",
+                            plan->budget_hit ? "output_budget" : "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 has_more = continuation_supported && sg_page_has_more(total, offset, plan->returned);
+    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_higher_budget", true);
+    }
+    bool truncated = has_more || 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" : "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 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 +3868,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 +3956,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 +3973,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 +4035,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 +4055,99 @@ 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 cbm_vector_result_t *vresults, int semantic_total,
+                               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 ? 0 : offset;
+    if (semantic_only) {
+        meta_plan.returned = 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_total > 0 || semantic_only) {
+            cbm_tree_scalar_int(&sb, "semantic_total", semantic_total);
+            cbm_tree_scalar_int(&sb, "semantic_returned", plan->semantic_returned);
+            emit_semantic_results_toon(&sb, vresults, 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, !semantic_only);
+        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_total > 0 || semantic_only) {
+        yyjson_mut_obj_add_int(doc, root, "semantic_total", semantic_total);
+        yyjson_mut_obj_add_int(doc, root, "semantic_returned", plan->semantic_returned);
+        emit_semantic_results(doc, root, vresults, 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, !semantic_only);
+    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, int semantic_total,
+                             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 = total > 0 ? total : semantic_total;
+    int page_offset = total > 0 ? offset : 0;
+    if (!json_format) {
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        sg_emit_paging_tree(&sb, page_total, page_offset, &floor, 0, false, max_output_bytes,
+                            !semantic_only);
+        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_paging_json(doc, root, page_total, page_offset, &floor, 0, false, max_output_bytes,
+                        !semantic_only);
+    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 +4165,39 @@ 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 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 && 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 +4216,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,95 +4244,21 @@ 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, 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.");
-                    }
-                }
-            }
-            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);
-            }
-            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. */
+    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) {
         if (fields_owner) {
             yyjson_doc_free(fields_owner);
         }
@@ -3725,69 +4276,90 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
             true);
     }
 
+    /* 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};
-    cbm_store_search(store, &params, &out);
-
-    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);
-        }
+    if (!semantic_only) {
+        (void)cbm_store_search(store, &params, &out);
     }
 
-    /* Add diagnostic hint when zero results */
-    if (out.total == 0) {
+    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) {
-            yyjson_mut_obj_add_str(
-                doc, root, "hint",
-                "No results. Try removing the label filter or broadening the name_pattern regex.");
+            diagnostic_hint = "No results; remove label or broaden name_pattern.";
         } else if (name_pattern) {
-            yyjson_mut_obj_add_str(
-                doc, root, "hint",
-                "No nodes match this pattern. Check spelling or try a broader regex.");
+            diagnostic_hint = "No nodes match; check spelling or broaden the 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.");
+            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.";
     }
 
-    bool sq_type_error = run_semantic_query(doc, root, args, store, project, limit);
+    int requested_fields = detail_ids ? 0 : nfields;
+    sg_render_plan_t plan = {
+        .returned = out.count,
+        .fields_returned = requested_fields,
+        .semantic_returned = vcount,
+        .connected_returned = !detail_ids && include_connected,
+        .core_hint_returned = diagnostic_hint != NULL,
+        .budget_hit = false,
+        .floor_exceeded = false,
+    };
 
-    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);
+    char *payload = NULL;
+    for (;;) {
+        payload =
+            sg_render_payload(json_format, &out, offset, fields, requested_fields, store,
+                              relationship, !detail_ids && include_connected, detail_ids, vresults,
+                              vcount, 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;
+        }
     }
 
-    char *json = yy_doc_to_str(doc);
-    yyjson_mut_doc_free(doc);
-    cbm_store_search_free(&out);
+    bool identity_available = out.count > 0 || vcount > 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, vcount, 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);
@@ -3795,16 +4367,261 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     free(file_pattern);
     free(relationship);
 
-    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;
 }
 
+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;
+}
+
+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);
+            }
+        } 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);
+            }
+        }
+        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);
+        }
+    }
+    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;
+}
+
+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) {
+    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) {
+        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) {
+    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);
+    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);
+    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);
+    }
+    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) {
+        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);
+    return json;
+}
+
+/* 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;
+    }
+
+    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 row_offset = cbm_mcp_get_int_arg(args, "offset", 0);
+    if (row_offset < 0) {
+        row_offset = 0;
+    }
 
     /* graph="missed" (#963): run the SAME cypher against the derived
      * miss-graph view (shadow project "<project>::missed") instead of the
@@ -3845,7 +4662,11 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
     }
 
     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";
@@ -3862,65 +4683,131 @@ 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);
+            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);
+    } 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);
+            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);
+                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);
+                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);
+            }
         }
-
-        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(query);
@@ -3937,10 +4824,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 +4842,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 +4851,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 +4864,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 +4876,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 +4916,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 +4936,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 +5065,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 +5109,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 +5218,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 +5268,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 +5291,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 +5315,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 +5343,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 +5370,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 +5402,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 +5422,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 +5432,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 +5445,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 +5466,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 +5494,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 +5868,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 +6033,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 +6150,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 +6307,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 +6407,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 +6444,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 +6678,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 +6701,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 +6769,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) {
+/* 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;
         }
-        const char *pj = tr->edges[e].properties_json;
-        if (!pj) {
-            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]));
         }
-        const char *args = strstr(pj, "\"args\"");
-        if (!args) {
+        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 *open = strchr(args, '[');
-        if (!open) {
+        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;
         }
-        int depth = 0;
-        const char *p = open;
-        for (; *p; p++) {
-            if (*p == '[') {
-                depth++;
-            } else if (*p == ']') {
-                depth--;
-                if (depth == 0) {
-                    p++;
-                    break;
-                }
+        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;
+        }
+    }
+    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 +6910,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 +6938,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 +6957,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 +6969,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 +6980,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 +7000,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 +7141,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 +7178,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 +7204,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 +7223,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 +7256,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 +7267,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 +7314,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 +7370,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 +7392,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 +7427,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 +7447,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 +7470,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 +7488,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 +7511,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 +7522,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 +7689,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 +7760,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 +7796,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 +7833,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 +7891,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 +7901,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 +7938,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 +7981,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 +8041,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 +8064,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 +8076,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 +8159,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 +8209,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 +8360,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 +9906,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 +9960,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 +9977,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,
@@ -8467,25 +10044,209 @@ static void add_snippet_coverage_note(yyjson_mut_doc *doc, yyjson_mut_val *root_
     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;
+    }
+    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++;
+    }
+    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 +10267,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 +10348,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 +10399,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 +10489,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 +10528,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 +10544,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 +10562,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 +10589,71 @@ 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];
+    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_lines;
     int match_count;
+    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 };
@@ -8822,7 +10761,12 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
 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) {
     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++) {
         bool dup = false;
@@ -8832,12 +10776,12 @@ static yyjson_mut_val *build_dedup_files_array(yyjson_mut_doc *doc, search_resul
                 break;
             }
         }
-        if (!dup && seen_count < CBM_SZ_512) {
+        if (!dup) {
             seen_files[seen_count++] = sr[fi].file;
             yyjson_mut_arr_add_str(doc, files_arr, sr[fi].file);
         }
     }
-    for (int fi = 0; fi < raw_count && seen_count < CBM_SZ_512; fi++) {
+    for (int fi = 0; fi < raw_count; fi++) {
         bool dup = false;
         for (int j = 0; j < seen_count; j++) {
             if (strcmp(seen_files[j], raw[fi].file) == 0) {
@@ -8850,24 +10794,37 @@ static yyjson_mut_val *build_dedup_files_array(yyjson_mut_doc *doc, search_resul
             yyjson_mut_arr_add_str(doc, files_arr, raw[fi].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 +10833,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 +10854,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 +10870,92 @@ 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 int count_truncated_raw_content(const grep_match_t *raw, int raw_count) {
+    int count = 0;
+    for (int i = 0; i < raw_count; i++) {
+        if (raw[i].content_truncated) {
+            count++;
+        }
+    }
+    return count;
 }
 
-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_count < match_limit ? result->match_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 +10963,164 @@ 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 gm_count, int output_count,
+                                         int raw_output, int directory_output, 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);
+    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[ri];
-        char lines[CBM_SZ_32];
         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);
+        const char **raw_cells = calloc((size_t)raw_output * 3U, sizeof(*raw_cells));
+        char (*line_text)[CBM_SZ_32] = calloc((size_t)raw_output, sizeof(*line_text));
+        if (!raw_cells || !line_text) {
+            free(line_text);
+            free(raw_cells);
+            cbm_sb_free(&sb);
+            return NULL;
+        }
         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);
+            snprintf(line_text[ri], sizeof(line_text[ri]), "%d", raw[ri].line);
+            raw_cells[(size_t)ri * 3U] = raw[ri].file;
+            raw_cells[(size_t)ri * 3U + 1U] = line_text[ri];
+            raw_cells[(size_t)ri * 3U + 2U] = raw[ri].content;
         }
+        static const bool raw_string_cols[] = {true, false, true};
+        static const bool raw_prefix_cols[] = {true, false, false};
+        cbm_tree_table_rows_profiled(&sb, "raw", raw_output, rcols, 3, raw_cells, raw_string_cols,
+                                     raw_prefix_cols);
+        free(line_text);
+        free(raw_cells);
     }
 
-    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) {
+    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;
+    }
+    if (directory_output > dir_n) {
+        directory_output = dir_n;
+    }
+    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++) {
+            snprintf(count_text[d], sizeof(count_text[d]), "%d", directories[d].count);
+            dir_cells[(size_t)d * 2U] = directories[d].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, "results_returned", output_count);
+    bool has_more = output_count < sr_count;
+    cbm_tree_scalar_bool(&sb, "has_more", has_more);
+    cbm_tree_scalar_int(&sb, "raw_returned", raw_output);
+    cbm_tree_scalar_bool(&sb, "raw_has_more", raw_output < raw_count);
+    int truncated_raw_content = count_truncated_raw_content(raw, raw_count);
+    if (truncated_raw_content > 0) {
+        cbm_tree_scalar_int(&sb, "raw_content_truncated", truncated_raw_content);
+    }
+    cbm_tree_scalar_int(&sb, "directories_total", dir_n);
+    cbm_tree_scalar_int(&sb, "directories_returned", directory_output);
+    cbm_tree_scalar_bool(&sb, "directories_has_more", directory_output < dir_n);
+    if (scan_saturated) {
+        cbm_tree_scalar_bool(&sb, "scan_saturated", true);
+    }
+    cbm_tree_scalar_bool(&sb, "truncated",
+                         has_more || raw_output < raw_count || directory_output < dir_n ||
+                             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",
@@ -9060,27 +11138,31 @@ 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) {
+                                    int raw_count, int gm_count, int output_count, int raw_output,
+                                    int directory_output, 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, output_count, raw, 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]);
         }
@@ -9105,22 +11187,23 @@ 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");
@@ -9128,7 +11211,6 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
         yyjson_mut_arr_add_str(doc, rcols, "content");
         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++) {
             yyjson_mut_val *row = yyjson_mut_arr(doc);
             yyjson_mut_arr_add_str(doc, row, raw[ri].file);
@@ -9140,12 +11222,53 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
         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_output > dir_total) {
+        directory_output = dir_total;
+    }
+    yyjson_mut_val *directory_object = yyjson_mut_obj(doc);
+    for (int d = 0; d < directory_output; d++) {
+        yyjson_mut_val *key = yyjson_mut_strcpy(doc, directories[d].name);
+        yyjson_mut_val *value = yyjson_mut_int(doc, directories[d].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, "results_returned", output_count);
+    bool has_more = output_count < sr_count;
+    yyjson_mut_obj_add_bool(doc, root_obj, "has_more", has_more);
+    yyjson_mut_obj_add_int(doc, root_obj, "raw_returned", raw_output);
+    yyjson_mut_obj_add_bool(doc, root_obj, "raw_has_more", raw_output < raw_count);
+    int truncated_raw_content = count_truncated_raw_content(raw, raw_count);
+    if (truncated_raw_content > 0) {
+        yyjson_mut_obj_add_int(doc, root_obj, "raw_content_truncated", truncated_raw_content);
+    }
+    yyjson_mut_obj_add_int(doc, root_obj, "directories_total", dir_total);
+    yyjson_mut_obj_add_int(doc, root_obj, "directories_returned", directory_output);
+    yyjson_mut_obj_add_bool(doc, root_obj, "directories_has_more", directory_output < dir_total);
+    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_output < raw_count || directory_output < dir_total ||
+                                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 +11301,121 @@ 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 gm_count, int output_count, int raw_output,
+                                   int directory_output, 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, gm_count, output_count, raw_output, directory_output,
+            match_limit, scan_saturated, warn_literal_pipe, elapsed_ms, budget_hit, -1);
+    }
+
+    char *json = assemble_search_output(sr, sr_count, raw, raw_count, gm_count, output_count,
+                                        raw_output, directory_output, 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, row_count, row_count, 0,
+                                          row_count, 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, bool scan_saturated,
+                                 bool json_format, int max_output_tokens) {
+    if (!json_format) {
+        cbm_sb_t sb;
+        cbm_sb_init(&sb);
+        static const char *const cols[] = {"qn",      "label",           "file", "lines",
+                                           "matches", "matches_omitted", "in",   "out"};
+        cbm_tree_table_header(&sb, "results", 0, cols, 8);
+        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, "results_returned", 0);
+        cbm_tree_scalar_bool(&sb, "has_more", sr_count > 0);
+        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_str(&sb, "continuation",
+                            "raise max_output_tokens; no partial row 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_int(doc, root, "total_grep_matches", gm_count);
+    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_str(doc, root, "total_relation", scan_saturated ? "gte" : "eq");
+    yyjson_mut_obj_add_int(doc, root, "results_returned", 0);
+    yyjson_mut_obj_add_bool(doc, root, "has_more", sr_count > 0);
+    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_str(doc, root, "continuation",
+                           "raise max_output_tokens; no partial row was emitted");
+    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,16 +11432,45 @@ static const char *strip_root_prefix(const char *path, const char *root, size_t
     return p;
 }
 
+static int grep_match_cmp(const void *left, const void *right) {
+    const grep_match_t *a = left;
+    const grep_match_t *b = right;
+    int file_order = strcmp(a->file, b->file);
+    if (file_order != 0) {
+        return file_order;
+    }
+    return (a->line > b->line) - (a->line < b->line);
+}
+
 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 grep_limit, int *out_count, bool *out_saturated,
+                                          bool *out_oom) {
     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];
+    grep_match_t *gm = calloc((size_t)gm_cap, sizeof(*gm));
+    char *line = NULL;
+    size_t line_capacity = 0;
 
-    while (fgets(line, sizeof(line), fp) && gm_count < grep_limit) {
-        size_t len = strlen(line);
+    if (out_saturated) {
+        *out_saturated = false;
+    }
+    if (out_oom) {
+        *out_oom = gm == NULL;
+    }
+    if (!gm) {
+        *out_count = 0;
+        return NULL;
+    }
+    for (;;) {
+        ssize_t line_length = cbm_getline(&line, &line_capacity, fp);
+        if (line_length < 0) {
+            if (!feof(fp) && out_oom) {
+                *out_oom = true;
+            }
+            break;
+        }
+        size_t len = (size_t)line_length;
         while (len > 0 && (line[len - SKIP_ONE] == '\n' || line[len - SKIP_ONE] == '\r')) {
             line[--len] = '\0';
         }
@@ -9246,14 +11506,53 @@ static grep_match_t *collect_grep_matches(FILE *fp, const char *root_path, size_
             continue;
         }
 
-        safe_grow(gm, gm_count, gm_cap, PAIR_LEN);
-        snprintf(gm[gm_count].file, sizeof(gm[0].file), "%s", file);
+        if (gm_count >= grep_limit) {
+            if (out_saturated) {
+                *out_saturated = true;
+            }
+            break;
+        }
+
+        if (gm_count >= gm_cap) {
+            int next_capacity = gm_cap * PAIR_LEN;
+            grep_match_t *grown = realloc(gm, (size_t)next_capacity * sizeof(*gm));
+            if (!grown) {
+                if (out_oom) {
+                    *out_oom = true;
+                }
+                break;
+            }
+            memset(grown + gm_cap, 0, (size_t)(next_capacity - gm_cap) * sizeof(*grown));
+            gm = grown;
+            gm_cap = next_capacity;
+        }
+        gm[gm_count].file = heap_strdup(file);
+        if (!gm[gm_count].file) {
+            if (out_oom) {
+                *out_oom = true;
+            }
+            break;
+        }
         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);
+        const char *content = sep2 + SKIP_ONE;
+        size_t content_length = strlen(content);
+        gm[gm_count].content_truncated = content_length >= sizeof(gm[gm_count].content);
+        size_t content_copy = content_length;
+        if (content_copy >= sizeof(gm[gm_count].content)) {
+            content_copy = sizeof(gm[gm_count].content) - SKIP_ONE;
+        }
+        memcpy(gm[gm_count].content, content, content_copy);
+        gm[gm_count].content[content_copy] = '\0';
+        sanitize_utf8_inplace(gm[gm_count].content);
         gm_count++;
     }
 
+    free(line);
+    if (out_oom && *out_oom) {
+        free_grep_matches(gm, gm_count);
+        *out_count = 0;
+        return NULL;
+    }
     *out_count = gm_count;
     return gm;
 }
@@ -9274,52 +11573,97 @@ 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) {
+    if (result->match_count >= result->match_capacity) {
+        int next_capacity = result->match_capacity > 0 ? result->match_capacity * PAIR_LEN : 8;
+        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_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 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) {
-            (*raw)[(*raw_count)++] = *hit;
+            int next_capacity = (*raw_cap == 0) ? CBM_SZ_32 : *raw_cap * PAIR_LEN;
+            grep_match_t *grown = realloc(*raw, (size_t)next_capacity * sizeof(**raw));
+            if (!grown) {
+                return false;
+            }
+            *raw = grown;
+            *raw_cap = next_capacity;
         }
+        (*raw)[*raw_count] = *hit;
+        hit->file = NULL;
+        (*raw_count)++;
     }
+    return true;
 }
 
 /* Free a file_nodes array returned from cbm_store_find_nodes_by_file. */
@@ -9336,10 +11680,12 @@ static void free_file_nodes(cbm_node_t *nodes, int count) {
 }
 
 /* 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,
+static bool 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);
+    if (gm_count > SKIP_ONE) {
+        qsort(gm, (size_t)gm_count, sizeof(*gm), grep_match_cmp);
+    }
     int i = 0;
     while (i < gm_count) {
         const char *cur_file = gm[i].file;
@@ -9353,11 +11699,15 @@ static void classify_all_grep_hits(grep_match_t *gm, int gm_count, cbm_store_t *
             cbm_store_find_nodes_by_file(store, project, cur_file, &file_nodes, &file_node_count);
         }
         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);
+            if (!classify_grep_hit(&gm[mi], file_nodes, file_node_count, sr, sr_count, sr_cap, raw,
+                                   raw_count, raw_cap)) {
+                free_file_nodes(file_nodes, file_node_count);
+                return false;
+            }
         }
         free_file_nodes(file_nodes, file_node_count);
     }
+    return true;
 }
 
 /* Write indexed file list for scoped grep. Returns true if scoped.
@@ -9383,8 +11733,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;
@@ -9652,6 +12007,47 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     int mode = parse_search_mode(mode_str);
     free(mode_str);
 
+    if (limit < 1) {
+        limit = 1;
+    } else if (limit > 500) {
+        limit = 500;
+    }
+    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 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 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);
@@ -9790,13 +12186,16 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
 
     /* Collect grep matches into array */
     int gm_count = 0;
+    bool scan_saturated = false;
+    bool grep_oom = false;
     grep_match_t *gm = NULL;
     if (scoped && scoped_written == 0) {
         /* The path_filter 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 */
+        gm = calloc(1U, sizeof(*gm)); /* empty set; freed below */
+        grep_oom = gm == NULL;
         search_scratch_close(&scratch);
     } else {
         char cmd[CBM_SZ_4K];
@@ -9814,13 +12213,25 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         }
 
         gm = collect_grep_matches(fp, root_path, strlen(root_path), has_path_filter, &path_regex,
-                                  grep_limit, &gm_count);
+                                  grep_limit, &gm_count, &scan_saturated, &grep_oom);
         cbm_pclose(fp);
         /* 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);
     }
 
+    if (grep_oom) {
+        free_grep_matches(gm, gm_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);
+    }
+
     /* ── 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. */
@@ -9829,23 +12240,49 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
 
     int sr_cap = CBM_SZ_32;
     int sr_count = 0;
-    search_result_t *sr = calloc(sr_cap, sizeof(search_result_t));
+    search_result_t *sr = calloc((size_t)sr_cap, sizeof(*sr));
 
     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);
+    grep_match_t *raw = calloc((size_t)raw_cap, sizeof(*raw));
+
+    if (!sr || !raw ||
+        !classify_all_grep_hits(gm, gm_count, store, project, &sr, &sr_count, &sr_cap, &raw,
+                                &raw_count, &raw_cap)) {
+        free_grep_matches(gm, gm_count);
+        free_search_results(sr, sr_count);
+        free_grep_matches(raw, raw_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);
+    }
 
     /* 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_grep_matches(gm, gm_count);
+            free_search_results(sr, sr_count);
+            free_grep_matches(raw, raw_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 +12308,133 @@ 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 output_count = sr_count < limit ? sr_count : limit;
+    int raw_output = raw_count < raw_limit ? raw_count : raw_limit;
+    search_dir_count_t *directories = NULL;
+    int dir_total = 0;
+    if (!aggregate_search_dirs(sr, sr_count, &directories, &dir_total)) {
+        free_grep_matches(gm, gm_count);
+        free_search_results(sr, sr_count);
+        free_grep_matches(raw, raw_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_output = dir_total < directory_limit ? dir_total : 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, gm_count, output_count, raw_output, directory_output,
+        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, gm_count, output_count,
+                                        raw_output, directory_output, 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, gm_count, output_count,
+                                        raw_output, directory_output, 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, gm_count, output_count,
+                                        raw_output, directory_output, 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, gm_count, output_count, raw_output, directory_output,
+                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, gm_count, output_count, raw_output, directory_output,
+                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, gm_count, candidate_rows, raw_output,
+                directory_output, 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, 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_grep_matches(gm, gm_count);
+    free_search_results(sr, sr_count);
+    free_grep_matches(raw, raw_count);
     free(root_path);
     free(pattern);
     free(project);
@@ -10112,23 +12654,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 +12673,140 @@ 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 line reader. Git permits paths longer than the
+ * former 1 KiB stack buffer on supported platforms; splitting one path into
+ * several fake files would corrupt both traversal seeds and output. */
+static char *detect_read_line(FILE *stream, bool *oom) {
+    cbm_sb_t line;
+    cbm_sb_init(&line);
+    bool saw_byte = false;
+    for (;;) {
+        int ch = fgetc(stream);
+        if (ch == EOF) {
+            break;
         }
-        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);
+        saw_byte = true;
+        char byte = (char)ch;
+        cbm_sb_append_n(&line, &byte, 1);
+        if (line.oom || ch == '\n') {
+            break;
+        }
+    }
+    if (line.oom) {
+        if (oom) {
+            *oom = true;
+        }
+        cbm_sb_free(&line);
+        return NULL;
     }
-    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);
+    if (!saw_byte) {
+        cbm_sb_free(&line);
+        return NULL;
     }
+    return cbm_sb_finish(&line);
 }
 
 static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
@@ -10365,8 +12961,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     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. */
+    /* 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,6 +12971,36 @@ 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;
     }
+    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;
+    }
 
     /* Collect changed file paths into a C array (drives seeds, the rollup, and
      * both output encodings). */
@@ -10454,13 +13081,18 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         }
     }
 
-    char line[CBM_SZ_1K];
-    while (fgets(line, sizeof(line), fp)) {
+    bool changed_line_oom = false;
+    for (;;) {
+        char *line = detect_read_line(fp, &changed_line_oom);
+        if (!line) {
+            break;
+        }
         size_t len = strlen(line);
         while (len > 0 && (line[len - SKIP_ONE] == '\n' || line[len - SKIP_ONE] == '\r')) {
             line[--len] = '\0';
         }
         if (len == 0) {
+            free(line);
             continue;
         }
         /* Strip the `git status --porcelain` 2-char code + space; for a rename
@@ -10476,6 +13108,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             }
         }
         if (path_line[0] == '\0') {
+            free(line);
             continue;
         }
         /* Dedup: the three git sources are sorted+unioned on POSIX but not on
@@ -10488,6 +13121,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             }
         }
         if (dup) {
+            free(line);
             continue;
         }
         if (file_count >= file_cap) {
@@ -10499,9 +13133,24 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             detect_collect_seeds(store, project, path_line, hunks, hunk_count, &seeds, &seed_count,
                                  &seed_cap);
         }
+        free(line);
     }
     (void)fclose(fp);
     (void)cbm_unlink(output_path);
+    if (changed_line_oom) {
+        for (int i = 0; i < file_count; i++) {
+            free(files[i]);
+        }
+        free(files);
+        free(seeds);
+        free(hunks);
+        free(direction);
+        free(root_path);
+        free(project);
+        free(base_branch);
+        free(scope);
+        return cbm_mcp_text_result("out of memory while reading changed paths", true);
+    }
     int git_status = git_result.exit_code;
 
     /* merge-base SHA: the exact commit the diff is measured against, so the
@@ -10565,8 +13214,42 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     }
 
     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;
+    }
+
+    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);
+    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:
     if (!legacy_json) {
         cbm_sb_t sb;
         cbm_sb_init(&sb);
@@ -10575,6 +13258,13 @@ 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 (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 (is_error) {
             char hint_buf[CBM_SZ_256];
             snprintf(hint_buf, sizeof(hint_buf),
@@ -10582,40 +13272,70 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
                      base_branch);
             cbm_tree_scalar_str(&sb, "hint", hint_buf);
         }
-        /* changed files (the git result) */
+        /* 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);
+        bool changed_has_more = changed_start + changed_returned < file_count;
+        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);
+        } else if (changed_has_more) {
+            cbm_tree_scalar_bool(&sb,
+                                 changed_limit == 0 ? "changed_continuation_requires_positive_limit"
+                                                    : "changed_continuation_requires_higher_budget",
+                                 true);
+        }
         char cf[CBM_SZ_64];
-        snprintf(cf, sizeof(cf), "changed_files: %d\n", file_count);
+        snprintf(cf, sizeof(cf), "changed_files: %d\n", changed_returned);
         cbm_sb_append(&sb, cf);
-        for (int i = 0; i < file_count; i++) {
+        for (int i = changed_start; i < changed_start + changed_returned; i++) {
             cbm_sb_append(&sb, "  ");
             cbm_sb_append(&sb, files[i]);
             cbm_sb_append(&sb, "\n");
         }
         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, truncated);
+            /* 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", truncated ? "gte" : "eq");
+            cbm_tree_scalar_int(&sb, "module_returned", module_returned);
+            bool module_has_more = module_start + module_returned < module_total;
+            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);
+            } 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");
             }
+            free(count_text);
+            free(cells);
             if (truncated) {
                 cbm_tree_scalar_bool(&sb, "truncated", true);
                 cbm_tree_scalar_str(&sb, "hint",
@@ -10634,17 +13354,38 @@ 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);
+        }
+        yyjson_mut_obj_add_int(doc, root_obj, "changed_total", file_count);
+        yyjson_mut_obj_add_int(doc, root_obj, "changed_returned", changed_returned);
+        bool changed_has_more = changed_start + changed_returned < file_count;
+        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);
+        } 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", truncated ? "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,30 +13399,45 @@ 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);
-                }
-                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);
+        bool impacted_has_more = imp_start + imp_returned < impact.visited_count;
+        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);
+        } 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",
+                                   truncated ? "gte" : "eq");
+            yyjson_mut_obj_add_int(doc, root_obj, "module_returned", module_returned);
+            bool module_has_more = module_start + module_returned < module_total;
+            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);
+            } 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_val(doc, root_obj, "impacted_modules", rollup);
         }
         yyjson_mut_obj_add_bool(doc, root_obj, "truncated", truncated);
         if (is_error) {
@@ -10695,7 +13451,61 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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, "output_budget_floor_exceeded", 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, "output_budget_floor_exceeded", 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]);
     }
@@ -10728,13 +13538,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 +13554,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 +13736,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 +13894,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 +13917,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 +13932,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;
 }
diff --git a/src/mcp/mcp_internal.h b/src/mcp/mcp_internal.h
index 313a4d1ce..a7dd66935 100644
--- a/src/mcp/mcp_internal.h
+++ b/src/mcp/mcp_internal.h
@@ -49,4 +49,13 @@ 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
+/* 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);
+#endif
+
 #endif
diff --git a/src/store/store.c b/src/store/store.c
index d91346e67..24f20ed62 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"
@@ -4451,10 +4452,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 +4471,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 +4510,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 +4557,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 +4592,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 +4649,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 +4692,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 +4719,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:
diff --git a/src/store/store.h b/src/store/store.h
index 65f4971f8..f63fd7ae1 100644
--- a/src/store/store.h
+++ b/src/store/store.h
@@ -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 ───────────────────────────────────────── */
@@ -600,6 +602,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..85bf35f8b 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>
@@ -99,6 +100,53 @@ 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();
+}
+
 enum { CLI_PROGRESS_RACE_THREADS = 4, CLI_PROGRESS_RACE_ROUNDS = 32 };
 
 typedef struct {
@@ -7817,6 +7865,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 +9307,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;
@@ -12412,6 +12561,8 @@ SUITE(cli) {
     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_serializes_concurrent_callbacks);
     RUN_TEST(cli_sha256_file_matches_known_vector);
     RUN_TEST(cli_checksum_manifest_requires_exact_filename_and_accepts_star);
@@ -12620,6 +12771,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 +12798,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);
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_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..c94afedda 100644
--- a/tests/test_incremental.c
+++ b/tests/test_incremental.c
@@ -1568,26 +1568,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();
 }
@@ -2262,8 +2265,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_log.c b/tests/test_log.c
index 562768567..3dcfd35d4 100644
--- a/tests/test_log.c
+++ b/tests/test_log.c
@@ -55,15 +55,29 @@ static const char *capture_end(void) {
 }
 
 TEST(log_level_default) {
-    /* Default level should be INFO */
+    /* Routine informational output is opt-in; libraries start quiet. */
+    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_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 +86,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 +100,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 +112,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 +125,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 +138,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 +153,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 +171,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 +185,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 +249,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 +274,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 +293,13 @@ 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_level_set);
     RUN_TEST(log_info_output);
     RUN_TEST(log_filtered_by_level);
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 1d99d71ad..ff18afc15 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -601,6 +601,282 @@ TEST(tree_cell_sanitizes_control_and_invalid_utf8) {
     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();
+}
+
+/* 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);
+    ASSERT_NOT_NULL(strstr(out, "\"123456789012.\""));
+    ASSERT_NOT_NULL(strstr(out, "  @0+member_00\n"));
+    free(out);
+    PASS();
+}
+
 /* ══════════════════════════════════════════════════════════════════
  *  JSON-RPC PARSING
  * ══════════════════════════════════════════════════════════════════ */
@@ -836,13 +1112,48 @@ 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, "Regex 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_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), 16 * 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;
@@ -1637,6 +1948,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 +2137,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 +2150,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 +2177,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 +2221,7 @@ TEST(tool_get_architecture_cycles_detects_scc) {
     free(inner);
     free(resp);
     cbm_mcp_server_free(srv);
+    free(long_cycle_qn);
     PASS();
 }
 
@@ -1821,10 +2271,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,6 +2317,171 @@ TEST(tool_get_code_snippet_clips_whole_file_node) {
     PASS();
 }
 
+TEST(tool_get_code_snippet_omits_over_budget_whole_line) {
+    char tmp[256];
+    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);
+
+    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);
+
+    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
@@ -1946,7 +2594,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 +2643,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 +2838,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 +2864,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_NULL(strstr(inner, "\"git\""));
+    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);
 
-    /* ...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}}}");
+    /* 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, "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,"
+                                   "\"format\":\"json\"}}}");
     ASSERT_NOT_NULL(resp);
     inner = extract_text_content(resp);
     ASSERT_NOT_NULL(inner);
@@ -2246,7 +3003,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,6 +3079,235 @@ TEST(tool_search_graph_query_honors_file_pattern_issue552) {
     PASS();
 }
 
+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);
+
+    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_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 *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);
+
+    /* 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);
+
+    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);
+
+    /* 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);
+    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). */
@@ -2366,6 +3352,561 @@ TEST(tool_query_graph_basic) {
     PASS();
 }
 
+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);
+    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, "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);
+    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);
+
+    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);
+
+    /* 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);
+    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_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);
+    PASS();
+}
+
+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 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(response);
+
+    cbm_mcp_server_free(srv);
+    PASS();
+}
+
+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);
+
+    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();
+}
+
+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);
+    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);
+    }
+
+    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);
+    }
+    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();
+}
+
+/* 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();
 
@@ -2411,8 +3952,9 @@ TEST(tool_check_index_coverage_finds_path_beyond_status_cap) {
     }
     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\"}");
+    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);
@@ -2423,13 +3965,16 @@ TEST(tool_check_index_coverage_finds_path_beyond_status_cap) {
 
     char *coverage = cbm_mcp_handle_tool(
         srv, "check_index_coverage",
-        "{\"project\":\"coverage-cap-regression\",\"paths\":[\"src/partial-0501.c\"]}");
+        "{\"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, "777-790"));
+    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);
@@ -2439,6 +3984,91 @@ TEST(tool_check_index_coverage_finds_path_beyond_status_cap) {
     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));
@@ -2459,7 +4089,7 @@ TEST(tool_check_index_coverage_reports_paths_scopes_and_ranges) {
         cbm_mcp_handle_tool(srv, "check_index_coverage",
                             "{\"project\":\"test-project\","
                             "\"paths\":[\"main.go\",\"generated/pkg/a.c\",\"../escape.c\"],"
-                            "\"scopes\":[\".\"]}");
+                            "\"scopes\":[\".\"],\"format\":\"json\"}");
     ASSERT_NOT_NULL(coverage);
     char *inner = extract_text_content(coverage);
     ASSERT_NOT_NULL(inner);
@@ -2489,7 +4119,8 @@ TEST(tool_check_index_coverage_preserves_multiple_scope_labels) {
 
     char *coverage = cbm_mcp_handle_tool(srv, "check_index_coverage",
                                          "{\"project\":\"test-project\","
-                                         "\"scopes\":[\"alpha/one\",\"bravo/two\",\"charl/tri\"]}");
+                                         "\"scopes\":[\"alpha/one\",\"bravo/two\",\"charl/tri\"],"
+                                         "\"format\":\"json\"}");
     ASSERT_NOT_NULL(coverage);
     char *inner = extract_text_content(coverage);
     ASSERT_NOT_NULL(inner);
@@ -2540,7 +4171,8 @@ TEST(tool_check_index_coverage_rejects_stale_generation) {
     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\"]}");
+                                         "{\"project\":\"test-project\",\"paths\":[\"main.go\"],"
+                                         "\"format\":\"json\"}");
     ASSERT_NOT_NULL(response);
     char *inner = extract_text_content(response);
     ASSERT_NOT_NULL(inner);
@@ -2569,7 +4201,8 @@ TEST(tool_check_index_coverage_requires_source_when_file_metadata_changed) {
               CBM_STORE_OK);
 
     char *response = cbm_mcp_handle_tool(srv, "check_index_coverage",
-                                         "{\"project\":\"test-project\",\"paths\":[\"main.go\"]}");
+                                         "{\"project\":\"test-project\",\"paths\":[\"main.go\"],"
+                                         "\"format\":\"json\"}");
     ASSERT_NOT_NULL(response);
     char *inner = extract_text_content(response);
     ASSERT_NOT_NULL(inner);
@@ -2600,7 +4233,8 @@ TEST(tool_check_index_coverage_surfaces_lookup_errors) {
 
     char *response = cbm_mcp_handle_tool(
         srv, "check_index_coverage",
-        "{\"project\":\"test-project\",\"paths\":[\"main.go\"],\"scopes\":[\".\"]}");
+        "{\"project\":\"test-project\",\"paths\":[\"main.go\"],\"scopes\":[\".\"],"
+        "\"format\":\"json\"}");
     ASSERT_NOT_NULL(response);
     char *inner = extract_text_content(response);
     ASSERT_NOT_NULL(inner);
@@ -2623,10 +4257,11 @@ TEST(tool_index_status_includes_git_metadata) {
     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}}}");
+    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);
@@ -2835,8 +4470,8 @@ TEST(tool_trace_union_records_min_hop_across_seeds) {
     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"));
+    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);
@@ -2927,7 +4562,7 @@ TEST(tool_trace_pagination_exactly_once) {
     /* 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);
+        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)) {
@@ -2962,6 +4597,63 @@ TEST(tool_trace_pagination_exactly_once) {
     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");
@@ -2983,6 +4675,615 @@ TEST(tool_trace_pagination_exactly_once) {
     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. */
@@ -3174,17 +5475,291 @@ TEST(tool_trace_path_evidence_is_opt_in_and_class_mapped) {
     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"));
+    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
@@ -4012,102 +6587,463 @@ TEST(tool_search_code_missing_pattern) {
     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);
+/* #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(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);
+
+    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();
+}
+
+TEST(tool_search_code_no_project) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+
+    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_mcp_server_free(srv);
+    PASS();
+}
+
+TEST(search_code_multi_word) {
+    char tmp[512];
+    cbm_mcp_server_t *srv = setup_snippet_server(tmp, sizeof(tmp));
+    ASSERT_NOT_NULL(srv);
+
+    /* 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 *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();
+}
+
+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);
+
+    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"));
+
+    free(inner);
+    free(response);
+    cbm_mcp_server_free(srv);
+    cbm_unlink(src_path);
+    cbm_rmdir(tmp);
+    PASS();
+}
+
+TEST(search_code_reports_scan_saturation) {
+    char tmp[256];
+    snprintf(tmp, sizeof(tmp), "/tmp/cbm_srch_sat_XXXXXX");
+    ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+    char src_path[512];
+    snprintf(src_path, sizeof(src_path), "%s/many.c", tmp);
+    FILE *fp = cbm_fopen(src_path, "wb");
+    ASSERT_NOT_NULL(fp);
+    for (int i = 0; i < 501; i++) {
+        fprintf(fp, "int saturationneedle_%d = %d;\n", i, i);
+    }
+    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-saturation";
+    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",
+                       .qualified_name = "search-saturation.many",
+                       .file_path = "many.c",
+                       .start_line = 1,
+                       .end_line = 501};
+    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":97,\"method\":\"tools/call\","
+             "\"params\":{\"name\":\"search_code\",\"arguments\":{"
+             "\"pattern\":\"saturationneedle\",\"project\":\"search-saturation\","
+             "\"format\":\"json\"}}}");
+    ASSERT_NOT_NULL(resp);
+    char *inner = extract_text_content(resp);
+    ASSERT_NOT_NULL(inner);
+    ASSERT_NOT_NULL(strstr(inner, "\"total_grep_matches\":500"));
+    ASSERT_NOT_NULL(strstr(inner, "\"total_relation\":\"gte\""));
+    ASSERT_NOT_NULL(strstr(inner, "\"scan_saturated\":true"));
+    ASSERT_NOT_NULL(strstr(inner, "\"truncated\":true"));
+    free(inner);
+    free(resp);
+    cbm_mcp_server_free(srv);
+    cbm_unlink(src_path);
+    cbm_rmdir(tmp);
+    PASS();
+}
+
+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);
+    }
+    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);
+
     cbm_mcp_server_free(srv);
+    cbm_unlink(src_path);
+    cbm_rmdir(tmp);
     PASS();
 }
 
-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);
-
-    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;
-        }
+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;
     }
-    bool declared = minimum && yyjson_is_int(minimum) && yyjson_get_int(minimum) >= 1;
+    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_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(resp);
-    cbm_mcp_server_free(srv);
-
-    ASSERT_TRUE(declared);
+    free(json);
+    free(qualified_names[0]);
+    free(qualified_names[1]);
+    free(file_paths[0]);
+    free(file_paths[1]);
     PASS();
 }
 
-TEST(tool_search_code_no_project) {
+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\":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 *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();
 }
 
-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 <= 100; 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 = 100};
+    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)), 92);
+    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 92"));
+    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)), 100);
+    ASSERT_EQ((int)yyjson_get_int(yyjson_arr_get(row, 5)), 0);
+    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 +7535,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). */
@@ -6740,6 +9748,277 @@ TEST(tool_detect_changes_contained_commands_clean_up_error_and_success) {
     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_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_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_EQ(yyjson_get_int(yyjson_obj_get(root, "impacted_next_offset")), 1);
+    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_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_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_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);
+
+    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();
+}
+
 /* 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
@@ -7241,7 +10520,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 +10882,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 +12055,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)) {
@@ -10516,6 +13808,9 @@ SUITE(mcp) {
     RUN_TEST(jsonrpc_parse_notification);
     RUN_TEST(jsonrpc_parse_invalid);
     RUN_TEST(tree_cell_sanitizes_control_and_invalid_utf8);
+    RUN_TEST(json_to_tree_uses_header_once_rows_without_losing_metadata);
+    RUN_TEST(json_to_tree_keeps_multiline_source_readable);
+    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 +13833,7 @@ 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_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);
@@ -10596,20 +13892,33 @@ 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_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_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 +13932,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);
@@ -10649,6 +13966,12 @@ SUITE(mcp) {
     RUN_TEST(tool_search_code_limit_declares_a_minimum_issue1511);
     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_reports_scan_saturation);
+    RUN_TEST(search_code_default_budget_limits_raw_rows_before_graph_results);
+    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_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 +13984,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);
@@ -10682,6 +14007,7 @@ SUITE(mcp) {
     RUN_TEST(tool_manage_adr_get_accepts_symlink_path);
     RUN_TEST(tool_detect_changes_not_found_rich_error);
     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(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/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))

From 339f0c2de57d1058754cd96564de558bf5a2bf13 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 02:05:10 +0200
Subject: [PATCH 02/26] fix(mcp): preserve lean output continuations

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md        |   2 +-
 src/mcp/mcp.c    | 901 +++++++++++++++++++++++++++++++----------------
 tests/test_mcp.c | 621 +++++++++++++++++++++++++++++++-
 3 files changed, 1210 insertions(+), 314 deletions(-)

diff --git a/README.md b/README.md
index 63c83703b..67ee97c18 100644
--- a/README.md
+++ b/README.md
@@ -580,7 +580,7 @@ When stderr is an interactive terminal, the CLI automatically shows lifecycle an
 
 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 that table is at least 15% and 64 bytes smaller. 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. These are deterministic model-neutral byte savings that normally reduce tokens; 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` additionally exposes `raw_limit`, `directory_limit`, `match_limit`, and `source_max_lines`; its default retains eight match locations per graph result and reports the exact `matches_omitted` remainder. `detect_changes` pages changed files, impacted symbols, and module summaries independently.
+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` additionally exposes `raw_limit`/`raw_offset`, `directory_limit`/`directory_offset`, `match_limit`, and `source_max_lines`; its default retains eight match locations per graph result and reports the exact `matches_omitted` remainder. The ranked graph answer stays intact while raw matches and directory summaries page independently. `detect_changes` pages changed files, impacted symbols, and module summaries independently.
 
 Use `cli <tool> --help` to see the flags generated from that tool's input schema:
 
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index c0630d34b..aa4936eff 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -524,20 +524,20 @@ static const tool_def_t TOOLS[] = {
      "\"required\":[\"project\"]}"},
 
     {"search_code", "Search code",
-     "Graph-augmented text search. compact (default) returns ranked symbols; full adds bounded "
-     "source; files returns paths. Narrow filters or raise limit when has_more.",
+     "Graph-ranked text search. compact returns symbols; full adds bounded source; files paths.",
      "{\"type\":\"object\",\"properties\":{\"pattern\":{\"type\":\"string\"},\"project\":{\"type\":"
      "\"string\"},\"file_pattern\":{\"type\":\"string\"},\"path_filter\":{\"type\":\"string\"},"
      "\"mode\":{\"type\":\"string\","
-     "\"enum\":[\"compact\",\"full\",\"files\"],\"default\":\"compact\",\"description\":\"compact "
-     "rows; full bounded source; files paths.\"},"
+     "\"enum\":[\"compact\",\"full\",\"files\"],\"default\":\"compact\"},"
      "\"context\":{\"type\":\"integer\"},"
      "\"regex\":{\"type\":\"boolean\",\"default\":false},\"limit\":{\"type\":\"integer\","
      "\"default\":10,\"minimum\":1,\"maximum\":500,\"description\":\"Ranked graph rows.\"},"
      "\"raw_limit\":{\"type\":\"integer\",\"default\":5,\"minimum\":0,\"maximum\":100,"
      "\"description\":\"Unclassified grep rows; set 0 to omit.\"},"
+     "\"raw_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
      "\"directory_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":0,"
      "\"maximum\":64,\"description\":\"Directory summary rows; set 0 to omit.\"},"
+     "\"directory_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
      "\"match_limit\":{\"type\":\"integer\",\"default\":8,\"minimum\":1,"
      "\"maximum\":500,\"description\":\"Locations per row; exact remainder in matches_omitted.\"},"
      "\"source_max_lines\":{\"type\":\"integer\",\"default\":20,\"minimum\":1,"
@@ -10680,7 +10680,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.
@@ -10759,7 +10778,8 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
 
 /* 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 output_count, grep_match_t *raw, int raw_start,
+                                               int raw_count) {
     yyjson_mut_val *files_arr = yyjson_mut_arr(doc);
     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;
@@ -10782,16 +10802,17 @@ static yyjson_mut_val *build_dedup_files_array(yyjson_mut_doc *doc, search_resul
         }
     }
     for (int fi = 0; fi < raw_count; fi++) {
+        int raw_index = raw_start + 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);
@@ -10964,10 +10985,11 @@ static char *search_match_lines_text(const search_result_t *result, int match_li
  * 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 output_count,
-                                         int raw_output, int directory_output, int match_limit,
-                                         bool scan_saturated, bool warn_literal_pipe,
-                                         uint64_t elapsed_ms, bool budget_hit,
-                                         int source_lines_returned) {
+                                         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);
@@ -11046,10 +11068,11 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
             return NULL;
         }
         for (int ri = 0; ri < raw_output; ri++) {
-            snprintf(line_text[ri], sizeof(line_text[ri]), "%d", raw[ri].line);
-            raw_cells[(size_t)ri * 3U] = raw[ri].file;
+            int raw_index = raw_start + ri;
+            snprintf(line_text[ri], sizeof(line_text[ri]), "%d", raw[raw_index].line);
+            raw_cells[(size_t)ri * 3U] = raw[raw_index].file;
             raw_cells[(size_t)ri * 3U + 1U] = line_text[ri];
-            raw_cells[(size_t)ri * 3U + 2U] = raw[ri].content;
+            raw_cells[(size_t)ri * 3U + 2U] = raw[raw_index].content;
         }
         static const bool raw_string_cols[] = {true, false, true};
         static const bool raw_prefix_cols[] = {true, false, false};
@@ -11065,8 +11088,11 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
         cbm_sb_free(&sb);
         return NULL;
     }
-    if (directory_output > dir_n) {
-        directory_output = dir_n;
+    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"};
@@ -11080,8 +11106,10 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
             return NULL;
         }
         for (int d = 0; d < directory_output; d++) {
-            snprintf(count_text[d], sizeof(count_text[d]), "%d", directories[d].count);
-            dir_cells[(size_t)d * 2U] = directories[d].name;
+            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};
@@ -11101,20 +11129,39 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
     bool has_more = output_count < sr_count;
     cbm_tree_scalar_bool(&sb, "has_more", has_more);
     cbm_tree_scalar_int(&sb, "raw_returned", raw_output);
-    cbm_tree_scalar_bool(&sb, "raw_has_more", raw_output < raw_count);
+    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);
+    }
     int truncated_raw_content = count_truncated_raw_content(raw, raw_count);
     if (truncated_raw_content > 0) {
         cbm_tree_scalar_int(&sb, "raw_content_truncated", truncated_raw_content);
     }
     cbm_tree_scalar_int(&sb, "directories_total", dir_n);
     cbm_tree_scalar_int(&sb, "directories_returned", directory_output);
-    cbm_tree_scalar_bool(&sb, "directories_has_more", directory_output < dir_n);
+    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_output < raw_count || directory_output < dir_n ||
-                             scan_saturated || budget_hit);
+                         has_more || raw_has_more || directories_has_more || scan_saturated ||
+                             budget_hit);
     if (budget_hit) {
         cbm_tree_scalar_str(&sb, "truncation_reason", "output_budget");
     }
@@ -11138,8 +11185,9 @@ 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 output_count, int raw_output,
-                                    int directory_output, int match_limit, int mode,
+                                    int raw_count, int gm_count, 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) {
@@ -11150,7 +11198,8 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
     yyjson_mut_doc_set_root(doc, root_obj);
 
     if (mode == MODE_FILES) {
-        yyjson_mut_val *files = build_dedup_files_array(doc, sr, output_count, raw, raw_output);
+        yyjson_mut_val *files =
+            build_dedup_files_array(doc, sr, output_count, raw, raw_start, raw_output);
         if (!files) {
             yyjson_mut_doc_free(doc);
             return NULL;
@@ -11212,10 +11261,11 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
         yyjson_mut_obj_add_val(doc, raw_obj, "cols", rcols);
         yyjson_mut_val *raw_arr = yyjson_mut_arr(doc);
         for (int ri = 0; ri < raw_output; ri++) {
+            int raw_index = raw_start + 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_val(raw_arr, row);
         }
         yyjson_mut_obj_add_val(doc, raw_obj, "rows", raw_arr);
@@ -11228,13 +11278,17 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
         yyjson_mut_doc_free(doc);
         return NULL;
     }
-    if (directory_output > dir_total) {
-        directory_output = dir_total;
+    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++) {
-        yyjson_mut_val *key = yyjson_mut_strcpy(doc, directories[d].name);
-        yyjson_mut_val *value = yyjson_mut_int(doc, directories[d].count);
+        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);
@@ -11249,20 +11303,40 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
     bool has_more = output_count < sr_count;
     yyjson_mut_obj_add_bool(doc, root_obj, "has_more", has_more);
     yyjson_mut_obj_add_int(doc, root_obj, "raw_returned", raw_output);
-    yyjson_mut_obj_add_bool(doc, root_obj, "raw_has_more", raw_output < raw_count);
+    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);
+    }
     int truncated_raw_content = count_truncated_raw_content(raw, raw_count);
     if (truncated_raw_content > 0) {
         yyjson_mut_obj_add_int(doc, root_obj, "raw_content_truncated", truncated_raw_content);
     }
     yyjson_mut_obj_add_int(doc, root_obj, "directories_total", dir_total);
     yyjson_mut_obj_add_int(doc, root_obj, "directories_returned", directory_output);
-    yyjson_mut_obj_add_bool(doc, root_obj, "directories_has_more", directory_output < dir_total);
+    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_output < raw_count || directory_output < dir_total ||
-                                scan_saturated || budget_hit);
+                            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");
     }
@@ -11313,21 +11387,24 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
  * 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 gm_count, int output_count, int raw_output,
-                                   int directory_output, int match_limit, int mode,
+                                   int raw_count, int gm_count, 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, gm_count, output_count, raw_output, directory_output,
-            match_limit, scan_saturated, warn_literal_pipe, elapsed_ms, budget_hit, -1);
+            sr, sr_count, raw, raw_count, gm_count, 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, gm_count, output_count,
-                                        raw_output, directory_output, match_limit, mode,
-                                        context_lines, source_max_lines, root_path, scan_saturated,
-                                        warn_literal_pipe, elapsed_ms, budget_hit);
+    char *json = assemble_search_output(
+        sr, sr_count, raw, raw_count, gm_count, 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;
     }
@@ -11366,9 +11443,10 @@ char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
         }
         initialized++;
     }
-    char *payload = render_search_payload(results, row_count, NULL, 0, row_count, row_count, 0,
-                                          row_count, row_count > 0 ? 1 : 0, 0, 0, 0, "", false,
-                                          false, 0, false, json_format);
+    char *payload = render_search_payload(
+        results, row_count, NULL, 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;
 }
@@ -12018,12 +12096,20 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     } 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 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;
@@ -12316,7 +12402,11 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     free(sc_format);
 
     int output_count = sr_count < limit ? sr_count : limit;
-    int raw_output = raw_count < raw_limit ? raw_count : raw_limit;
+    int raw_start = raw_offset < raw_count ? raw_offset : raw_count;
+    int raw_output = raw_count - raw_start;
+    if (raw_output > raw_limit) {
+        raw_output = raw_limit;
+    }
     search_dir_count_t *directories = NULL;
     int dir_total = 0;
     if (!aggregate_search_dirs(sr, sr_count, &directories, &dir_total)) {
@@ -12333,20 +12423,26 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         return cbm_mcp_text_result("out of memory", true);
     }
     free_search_dirs(directories, dir_total);
-    int directory_output = dir_total < directory_limit ? dir_total : directory_limit;
+    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, gm_count, output_count, raw_output, directory_output,
-        match_limit, mode, context_lines, source_max_lines, root_path, scan_saturated,
-        warn_literal_pipe, elapsed_ms, false, sc_legacy_json);
+        sr, sr_count, raw, raw_count, gm_count, 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, gm_count, output_count,
-                                        raw_output, directory_output, match_limit, mode,
-                                        context_lines, source_max_lines, root_path, scan_saturated,
-                                        warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, gm_count, 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
@@ -12354,18 +12450,20 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     while (payload && strlen(payload) > byte_budget && raw_output > 0) {
         raw_output--;
         free(payload);
-        payload = render_search_payload(sr, sr_count, raw, raw_count, gm_count, output_count,
-                                        raw_output, directory_output, match_limit, mode,
-                                        context_lines, source_max_lines, root_path, scan_saturated,
-                                        warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, gm_count, 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, gm_count, output_count,
-                                        raw_output, directory_output, match_limit, mode,
-                                        context_lines, source_max_lines, root_path, scan_saturated,
-                                        warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, gm_count, 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
@@ -12378,9 +12476,10 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         while (low <= high) {
             int middle = low + (high - low) / 2;
             char *candidate = render_search_payload(
-                sr, sr_count, raw, raw_count, gm_count, output_count, raw_output, directory_output,
-                match_limit, mode, context_lines, middle, root_path, scan_saturated,
-                warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+                sr, sr_count, raw, raw_count, gm_count, 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;
@@ -12398,9 +12497,10 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         } else {
             source_max_lines = 0;
             payload = render_search_payload(
-                sr, sr_count, raw, raw_count, gm_count, output_count, raw_output, directory_output,
-                match_limit, mode, context_lines, source_max_lines, root_path, scan_saturated,
-                warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+                sr, sr_count, raw, raw_count, gm_count, 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);
         }
     }
 
@@ -12412,9 +12512,10 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         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, gm_count, candidate_rows, raw_output,
-                directory_output, match_limit, mode, context_lines, source_max_lines, root_path,
-                scan_saturated, warn_literal_pipe, elapsed_ms, true, sc_legacy_json);
+                sr, sr_count, raw, raw_count, gm_count, 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;
@@ -12776,37 +12877,92 @@ static void detect_emit_impacted_tree(cbm_sb_t *sb, const cbm_traverse_result_t
     }
 }
 
-/* Portable, allocation-backed line reader. Git permits paths longer than the
- * former 1 KiB stack buffer on supported platforms; splitting one path into
- * several fake files would corrupt both traversal seeds and output. */
-static char *detect_read_line(FILE *stream, bool *oom) {
-    cbm_sb_t line;
-    cbm_sb_init(&line);
-    bool saw_byte = false;
+/* 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_byte = true;
+        saw_input = true;
+        if (ch == delimiter) {
+            if (terminated) {
+                *terminated = true;
+            }
+            break;
+        }
         char byte = (char)ch;
-        cbm_sb_append_n(&line, &byte, 1);
-        if (line.oom || ch == '\n') {
+        cbm_sb_append_n(&record, &byte, 1);
+        if (record.oom) {
             break;
         }
     }
-    if (line.oom) {
+    if (record.oom) {
         if (oom) {
             *oom = true;
         }
-        cbm_sb_free(&line);
+        cbm_sb_free(&record);
         return NULL;
     }
-    if (!saw_byte) {
-        cbm_sb_free(&line);
+    if (!saw_input) {
+        cbm_sb_free(&record);
         return NULL;
     }
-    return cbm_sb_finish(&line);
+    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;
 }
 
 static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
@@ -12869,69 +13025,6 @@ 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);
-        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);
-    }
-
-    /* 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. */
@@ -12953,14 +13046,318 @@ 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);
 
+    /* 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);
+    }
+
+    /* resolve_store already called via get_project_root above */
+    cbm_store_t *store = srv->store;
+
     /* 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. */
@@ -13002,11 +13399,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         max_output_tokens = 1000000;
     }
 
-    /* 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;
+    /* Changed paths drive traversal seeds and both output encodings. */
     int64_t *seeds = NULL;
     int seed_count = 0;
     int seed_cap = 0;
@@ -13032,21 +13425,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);
@@ -13081,128 +13476,14 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         }
     }
 
-    bool changed_line_oom = false;
-    for (;;) {
-        char *line = detect_read_line(fp, &changed_line_oom);
-        if (!line) {
-            break;
-        }
-        size_t len = strlen(line);
-        while (len > 0 && (line[len - SKIP_ONE] == '\n' || line[len - SKIP_ONE] == '\r')) {
-            line[--len] = '\0';
-        }
-        if (len == 0) {
-            free(line);
-            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') {
-            free(line);
-            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. */
+    if (want_symbols) {
         for (int i = 0; i < file_count; i++) {
-            if (strcmp(files[i], path_line) == 0) {
-                dup = true;
-                break;
-            }
-        }
-        if (dup) {
-            free(line);
-            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);
         }
-        free(line);
-    }
-    (void)fclose(fp);
-    (void)cbm_unlink(output_path);
-    if (changed_line_oom) {
-        for (int i = 0; i < file_count; i++) {
-            free(files[i]);
-        }
-        free(files);
-        free(seeds);
-        free(hunks);
-        free(direction);
-        free(root_path);
-        free(project);
-        free(base_branch);
-        free(scope);
-        return cbm_mcp_text_result("out of memory while reading changed paths", true);
-    }
-    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';
-                }
-            }
-        }
-        if (mbfp) {
-            (void)fclose(mbfp);
-        }
-        if (mb_output_path[0]) {
-            (void)cbm_unlink(mb_output_path);
-        }
-        if (mb_cancelled || mb_containment_failed) {
-            for (int i = 0; i < file_count; i++) {
-                free(files[i]);
-            }
-            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. */
@@ -13213,7 +13494,6 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
                                   MCP_BFS_LIMIT_MAX, &impact, &truncated);
     }
 
-    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) {
@@ -13265,13 +13545,6 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         if (output_budget_floor_exceeded) {
             cbm_tree_scalar_bool(&sb, "output_budget_floor_exceeded", true);
         }
-        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 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);
@@ -13286,14 +13559,23 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
                                                     : "changed_continuation_requires_higher_budget",
                                  true);
         }
-        char cf[CBM_SZ_64];
-        snprintf(cf, sizeof(cf), "changed_files: %d\n", changed_returned);
-        cbm_sb_append(&sb, cf);
-        for (int i = changed_start; i < changed_start + changed_returned; i++) {
-            cbm_sb_append(&sb, "  ");
-            cbm_sb_append(&sb, files[i]);
-            cbm_sb_append(&sb, "\n");
+        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_start, imp_returned, truncated);
@@ -13337,12 +13619,14 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             free(count_text);
             free(cells);
             if (truncated) {
-                cbm_tree_scalar_bool(&sb, "truncated", true);
                 cbm_tree_scalar_str(&sb, "hint",
                                     "impact hit the safety ceiling — narrow with a lower "
                                     "'depth' or a smaller diff");
             }
         }
+        if (truncated || output_budget_hit) {
+            cbm_tree_scalar_bool(&sb, "truncated", true);
+        }
         out_str = cbm_sb_finish(&sb);
     } else {
         /* format:"json" = json-stringified tree: same model, structured. */
@@ -13439,14 +13723,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             }
             yyjson_mut_obj_add_val(doc, root_obj, "impacted_modules", rollup);
         }
-        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_bool(doc, root_obj, "truncated", truncated || output_budget_hit);
         out_str = yy_doc_to_str(doc);
         yyjson_mut_doc_free(doc);
     }
@@ -13475,6 +13752,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
                 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);
                 cbm_tree_scalar_int(&floor, "max_output_bytes", (long long)output_budget_bytes);
                 cbm_tree_scalar_str(&floor, "hint",
@@ -13486,6 +13764,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
                 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);
                 yyjson_mut_obj_add_uint(floor_doc, floor, "max_output_bytes", output_budget_bytes);
                 yyjson_mut_obj_add_str(
@@ -13518,7 +13797,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     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;
 }
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index ff18afc15..2c9d7f5f5 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -513,7 +513,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;
@@ -6835,6 +6835,130 @@ TEST(search_code_default_budget_limits_raw_rows_before_graph_results) {
     PASS();
 }
 
+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));
+
+    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);
+
+    cbm_node_t nodes[] = {
+        {.project = project,
+         .label = "Route",
+         .name = "route_hit",
+         .qualified_name = "fixture.route_hit",
+         .file_path = "graph-a/route.c",
+         .start_line = 1,
+         .end_line = 1},
+        {.project = project,
+         .label = "Function",
+         .name = "function_hit",
+         .qualified_name = "fixture.function_hit",
+         .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"));
+
+    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);
+    PASS();
+}
+
 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);
@@ -9579,6 +9703,416 @@ TEST(tool_detect_changes_not_found_rich_error) {
     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 *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);
+    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_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 *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 *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_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
  * after opening that file must use fclose + unlink. The command hook then
  * rejects merge-base only when it reaches the contained subprocess helper, so
@@ -9741,7 +10275,7 @@ 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);
@@ -10019,6 +10553,82 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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
@@ -13969,6 +14579,7 @@ SUITE(mcp) {
     RUN_TEST(search_code_preserves_valid_utf8_source);
     RUN_TEST(search_code_reports_scan_saturation);
     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_preserves_multi_kib_identities_and_distinct_long_directories);
     RUN_TEST(search_code_long_raw_line_is_one_truthfully_truncated_match);
     RUN_TEST(search_code_match_locations_are_explicitly_bounded_and_expandable);
@@ -14006,8 +14617,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);

From 15694bdf4b7afc6eb72bf0b335d15fda426b232f Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 02:40:57 +0200
Subject: [PATCH 03/26] fix(output): preserve compact output safety signals

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md                     |  2 +-
 docs/CONFIGURATION.md         |  2 +-
 graph-ui/tsconfig.tsbuildinfo |  2 +-
 src/cli/progress_sink.c       | 22 +++++++++++++----
 src/foundation/log.c          |  8 +++++++
 src/foundation/log.h          |  9 ++++++-
 src/main.c                    |  8 ++++++-
 src/mcp/compact_out.c         | 27 +++++++++++++++------
 tests/test_cli.c              | 23 ++++++++++++++++++
 tests/test_diagnostics.c      |  3 ++-
 tests/test_index_supervisor.c | 45 +++++++++++++++++++++++++++++++++++
 tests/test_log.c              | 24 ++++++++++++++++++-
 tests/test_main.c             | 13 ++++++++++
 tests/test_mcp.c              | 16 +++++++++++++
 14 files changed, 186 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 67ee97c18..d8be161d4 100644
--- a/README.md
+++ b/README.md
@@ -679,7 +679,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/tsconfig.tsbuildinfo b/graph-ui/tsconfig.tsbuildinfo
index 5f1f5e115..0da71675b 100644
--- a/graph-ui/tsconfig.tsbuildinfo
+++ b/graph-ui/tsconfig.tsbuildinfo
@@ -1 +1 @@
-{"root":["./src/app.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/rpc.ts","./src/components/controltab.tsx","./src/components/displaysettingsmenu.tsx","./src/components/edgelines.tsx","./src/components/errorboundary.tsx","./src/components/filterpanel.tsx","./src/components/graphloader.tsx","./src/components/graphscene.test.ts","./src/components/graphscene.tsx","./src/components/graphtab.deadcode.test.tsx","./src/components/graphtab.filters.test.tsx","./src/components/graphtab.test.ts","./src/components/graphtab.tsx","./src/components/missedcallout.tsx","./src/components/nodecloud.tsx","./src/components/nodedetailpanel.test.tsx","./src/components/nodedetailpanel.tsx","./src/components/nodelabels.tsx","./src/components/nodetooltip.tsx","./src/components/projectcard.tsx","./src/components/resizehandle.tsx","./src/components/sidebar.tsx","./src/components/statstab.test.tsx","./src/components/statstab.tsx","./src/components/tabbar.tsx","./src/components/ui/badge.tsx","./src/components/ui/button.tsx","./src/components/ui/card.tsx","./src/components/ui/checkbox.tsx","./src/components/ui/input.tsx","./src/components/ui/scroll-area.tsx","./src/components/ui/separator.tsx","./src/hooks/usegraphdata.test.ts","./src/hooks/usegraphdata.ts","./src/hooks/useprojects.test.tsx","./src/hooks/useprojects.ts","./src/lib/colors.ts","./src/lib/density.test.ts","./src/lib/density.ts","./src/lib/i18n.test.ts","./src/lib/i18n.ts","./src/lib/types.ts","./src/lib/utils.ts"],"version":"5.9.3"}
\ No newline at end of file
+{"root":["./src/app.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/rpc.ts","./src/components/controltab.tsx","./src/components/edgelines.tsx","./src/components/errorboundary.tsx","./src/components/filterpanel.tsx","./src/components/graphscene.test.ts","./src/components/graphscene.tsx","./src/components/graphtab.test.ts","./src/components/graphtab.tsx","./src/components/nodecloud.tsx","./src/components/nodedetailpanel.tsx","./src/components/nodelabels.tsx","./src/components/nodetooltip.tsx","./src/components/projectcard.tsx","./src/components/resizehandle.tsx","./src/components/sidebar.tsx","./src/components/statstab.test.tsx","./src/components/statstab.tsx","./src/components/tabbar.tsx","./src/components/ui/badge.tsx","./src/components/ui/button.tsx","./src/components/ui/card.tsx","./src/components/ui/checkbox.tsx","./src/components/ui/input.tsx","./src/components/ui/scroll-area.tsx","./src/components/ui/separator.tsx","./src/hooks/usegraphdata.test.ts","./src/hooks/usegraphdata.ts","./src/hooks/useprojects.ts","./src/lib/colors.ts","./src/lib/i18n.test.ts","./src/lib/i18n.ts","./src/lib/types.ts","./src/lib/utils.ts"],"version":"5.9.3"}
\ No newline at end of file
diff --git a/src/cli/progress_sink.c b/src/cli/progress_sink.c
index 23868f2b2..f21c87f9f 100644
--- a/src/cli/progress_sink.c
+++ b/src/cli/progress_sink.c
@@ -33,6 +33,7 @@ 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);
 
@@ -187,6 +188,7 @@ void cbm_progress_sink_init(FILE *out) {
     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
@@ -210,6 +212,7 @@ void cbm_progress_sink_fini(void) {
         cbm_log_set_level(s_previous_log_level);
         s_raised_log_level = false;
     }
+    s_preserve_details = false;
     cbm_mutex_unlock(&s_sink_mutex);
 }
 
@@ -352,9 +355,10 @@ 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, but keep routine worker chatter out of the human progress
- * view. Logger callbacks do not include a trailing newline. */
-static void passthrough_failure(const char *line) {
+ * 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);
@@ -377,7 +381,14 @@ void cbm_progress_sink_fn(const char *line) {
         return;
     }
     if (strcmp(level, "warn") == 0 || strcmp(level, "error") == 0) {
-        passthrough_failure(line);
+        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;
     }
@@ -398,5 +409,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/foundation/log.c b/src/foundation/log.c
index 56116109d..0eb82078d 100644
--- a/src/foundation/log.c
+++ b/src/foundation/log.c
@@ -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 b8ee9bcc7..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: WARN; INFO is opt-in). */
+/* 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 727f01b44..ae8654d70 100644
--- a/src/main.c
+++ b/src/main.c
@@ -2423,7 +2423,13 @@ 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);
 
     cbm_mcp_tool_profile_t tool_profile = CBM_MCP_TOOL_PROFILE_ALL;
     if (role == CBM_DAEMON_PROCESS_MCP_CLIENT &&
diff --git a/src/mcp/compact_out.c b/src/mcp/compact_out.c
index c18c474fc..29745b925 100644
--- a/src/mcp/compact_out.c
+++ b/src/mcp/compact_out.c
@@ -216,6 +216,19 @@ static void append_value(cbm_sb_t *sb, const char *s) {
     }
 }
 
+/* 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(cbm_sb_t *sb, const char *s) {
+    if (!s || !*s || needs_quotes(s) || strpbrk(s, ":()\\")) {
+        append_quoted(sb, s ? s : "");
+    } else {
+        cbm_sb_append(sb, s);
+    }
+}
+
 /* ── Scalars ────────────────────────────────────────────────────── */
 
 void cbm_tree_scalar_str(cbm_sb_t *sb, const char *key, const char *val) {
@@ -802,7 +815,7 @@ static void json_tree_object_table(cbm_sb_t *sb, const char *key_name, yyjson_va
         return;
     }
     json_tree_indent(sb, depth);
-    cbm_sb_append(sb, key_name);
+    append_key(sb, key_name);
     char count[48];
     snprintf(count, sizeof(count), ": %zu  (cols:", yyjson_arr_size(array));
     cbm_sb_append(sb, count);
@@ -813,7 +826,7 @@ static void json_tree_object_table(cbm_sb_t *sb, const char *key_name, yyjson_va
     yyjson_val *unused;
     yyjson_obj_foreach(first, key_index, key_maximum, column, unused) {
         cbm_sb_append_n(sb, " ", 1);
-        cbm_sb_append(sb, yyjson_get_str(column));
+        append_key(sb, yyjson_get_str(column));
     }
     cbm_sb_append_n(sb, ")\n", 2);
 
@@ -843,7 +856,7 @@ static void json_tree_array(cbm_sb_t *sb, const char *key_name, yyjson_val *arra
     }
 
     json_tree_indent(sb, depth);
-    cbm_sb_append(sb, key_name);
+    append_key(sb, key_name);
     char count[48];
     snprintf(count, sizeof(count), ": %zu\n", yyjson_arr_size(array));
     cbm_sb_append(sb, count);
@@ -875,7 +888,7 @@ static void json_tree_array(cbm_sb_t *sb, const char *key_name, yyjson_val *arra
 static void json_tree_value(cbm_sb_t *sb, const char *key_name, yyjson_val *value, int depth) {
     if (depth >= JSON_TREE_MAX_DEPTH) {
         json_tree_indent(sb, depth);
-        cbm_sb_append(sb, key_name);
+        append_key(sb, key_name);
         cbm_sb_append(sb, ": ");
         char *encoded = yyjson_val_write(value, 0, NULL);
         append_value(sb, encoded ? encoded : "null");
@@ -885,7 +898,7 @@ static void json_tree_value(cbm_sb_t *sb, const char *key_name, yyjson_val *valu
     }
     if (yyjson_is_obj(value)) {
         json_tree_indent(sb, depth);
-        cbm_sb_append(sb, key_name);
+        append_key(sb, key_name);
         cbm_sb_append(sb, ":\n");
         size_t index;
         size_t maximum;
@@ -899,12 +912,12 @@ static void json_tree_value(cbm_sb_t *sb, const char *key_name, yyjson_val *valu
     } else if (yyjson_is_str(value) &&
                (strchr(yyjson_get_str(value), '\n') || strchr(yyjson_get_str(value), '\r'))) {
         json_tree_indent(sb, depth);
-        cbm_sb_append(sb, key_name);
+        append_key(sb, key_name);
         cbm_sb_append(sb, ": ");
         json_tree_block_string(sb, yyjson_get_str(value), depth);
     } else {
         json_tree_indent(sb, depth);
-        cbm_sb_append(sb, key_name);
+        append_key(sb, key_name);
         cbm_sb_append(sb, ": ");
         json_tree_scalar(sb, value);
         cbm_sb_append_n(sb, "\n", 1);
diff --git a/tests/test_cli.c b/tests/test_cli.c
index 85bf35f8b..64118c1c8 100644
--- a/tests/test_cli.c
+++ b/tests/test_cli.c
@@ -147,6 +147,28 @@ TEST(cli_progress_sink_suppresses_noise_and_preserves_failures) {
     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 {
@@ -12563,6 +12585,7 @@ SUITE(cli) {
     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);
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_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 3dcfd35d4..d52d27c88 100644
--- a/tests/test_log.c
+++ b/tests/test_log.c
@@ -55,7 +55,7 @@ static const char *capture_end(void) {
 }
 
 TEST(log_level_default) {
-    /* Routine informational output is opt-in; libraries start quiet. */
+    /* Raw startup is quiet until main applies its role-aware policy. */
     ASSERT_EQ(cbm_log_get_level(), CBM_LOG_WARN);
     PASS();
 }
@@ -74,6 +74,27 @@ TEST(log_level_env_keeps_info_and_debug_opt_in) {
     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);
@@ -300,6 +321,7 @@ TEST(log_level_from_env_invalid_ignored) {
 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 2c9d7f5f5..460090c4d 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -636,6 +636,21 @@ TEST(json_to_tree_keeps_multiline_source_readable) {
     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();
+}
+
 /* 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. */
@@ -14420,6 +14435,7 @@ SUITE(mcp) {
     RUN_TEST(tree_cell_sanitizes_control_and_invalid_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(tree_table_uses_prefix_dictionary_only_when_it_materially_wins);
     RUN_TEST(jsonrpc_parse_tools_call);
     RUN_TEST(jsonrpc_parse_string_id_issue253);

From c32ab34c3b03677b5e5edb7be7587a9794b4d66b Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 03:00:46 +0200
Subject: [PATCH 04/26] chore(output): satisfy final static checks

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/main.c    |   3 +-
 src/mcp/mcp.c | 127 +++++++++++++++++++++++---------------------------
 2 files changed, 59 insertions(+), 71 deletions(-)

diff --git a/src/main.c b/src/main.c
index ae8654d70..19ffcef63 100644
--- a/src/main.c
+++ b/src/main.c
@@ -2427,8 +2427,7 @@ int main(int argc, char **argv) {
      * 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;
+    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);
 
     cbm_mcp_tool_profile_t tool_profile = CBM_MCP_TOOL_PROFILE_ALL;
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index aa4936eff..0cd032888 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -11151,9 +11151,8 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
         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",
+                             directory_limit == 0 ? "directory_continuation_requires_positive_limit"
+                                                  : "directory_continuation_requires_higher_budget",
                              true);
     }
     if (scan_saturated) {
@@ -11325,11 +11324,11 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
         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);
+        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);
@@ -11394,17 +11393,17 @@ static char *render_search_payload(search_result_t *sr, int sr_count, grep_match
                                    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, gm_count, 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);
+        return assemble_search_output_toon(sr, sr_count, raw, raw_count, gm_count, 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, gm_count, 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);
+    char *json = assemble_search_output(sr, sr_count, raw, raw_count, gm_count, 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;
     }
@@ -11443,10 +11442,10 @@ char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
         }
         initialized++;
     }
-    char *payload = render_search_payload(
-        results, row_count, NULL, 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);
+    char *payload =
+        render_search_payload(results, row_count, NULL, 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;
 }
@@ -12438,11 +12437,11 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
 
     if (payload && strlen(payload) > byte_budget) {
         free(payload);
-        payload = render_search_payload(
-            sr, sr_count, raw, raw_count, gm_count, 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);
+        payload = render_search_payload(sr, sr_count, raw, raw_count, gm_count, 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
@@ -12450,20 +12449,20 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     while (payload && strlen(payload) > byte_budget && raw_output > 0) {
         raw_output--;
         free(payload);
-        payload = render_search_payload(
-            sr, sr_count, raw, raw_count, gm_count, 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);
+        payload = render_search_payload(sr, sr_count, raw, raw_count, gm_count, 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, gm_count, 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);
+        payload = render_search_payload(sr, sr_count, raw, raw_count, gm_count, 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
@@ -13069,10 +13068,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
 #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);
+    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;
@@ -13083,8 +13081,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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);
+        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') {
@@ -13131,8 +13128,8 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     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);
+    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);
@@ -13205,8 +13202,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
 #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);
+    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")
@@ -13256,10 +13252,10 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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);
+        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];
@@ -13278,8 +13274,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     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);
+    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;
@@ -13293,16 +13288,14 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             }
             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');
+            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)) {
+            if (!detect_add_changed_path(&files, &file_count, &file_cap, record + PAIR_LEN + 1U)) {
                 changed_path_oom = true;
                 free(record);
                 break;
@@ -13310,8 +13303,8 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             free(record);
             if (rename_or_copy) {
                 bool source_terminated = false;
-                char *source = detect_read_record(status_fp, '\0', &changed_path_oom,
-                                                  &source_terminated);
+                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;
@@ -13326,8 +13319,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         (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) {
+        !status_output_opened || changed_path_oom || changed_path_malformed) {
         for (int i = 0; i < file_count; i++) {
             free(files[i]);
         }
@@ -13474,12 +13466,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         if (hunk_output_path[0]) {
             (void)cbm_unlink(hunk_output_path);
         }
-    }
-
-    /* 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. */
-    if (want_symbols) {
+        /* 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++) {
             detect_collect_seeds(store, project, files[i], hunks, hunk_count, &seeds, &seed_count,
                                  &seed_cap);
@@ -13568,8 +13557,8 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             }
             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,
+            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);

From f8f524dae06430029d278afa7f786294ad1131b7 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 10:58:38 +0200
Subject: [PATCH 05/26] test(mcp): bind lean detect-changes accounting

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 tests/test_incremental.c | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/tests/test_incremental.c b/tests/test_incremental.c
index c94afedda..fed067f49 100644
--- a/tests/test_incremental.c
+++ b/tests/test_incremental.c
@@ -1911,12 +1911,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);
@@ -1964,7 +1974,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();
 }

From 21e0a264ece09811858e9ba1f2e50ba08c1af1d3 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 11:20:22 +0200
Subject: [PATCH 06/26] fix(output): preserve non-utf8 identities

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md             |   2 +
 src/mcp/compact_out.c | 162 +++++++++++++++++++++++++++++++++++-------
 src/mcp/compact_out.h |   7 ++
 src/mcp/mcp.c         | 128 ++++++++++++++++++++++++++-------
 tests/test_mcp.c      |  54 ++++++++++++--
 5 files changed, 295 insertions(+), 58 deletions(-)

diff --git a/README.md b/README.md
index d8be161d4..1eac25eac 100644
--- a/README.md
+++ b/README.md
@@ -582,6 +582,8 @@ Large compact-tree tables may start with a response-local `<section>_refs` direc
 
 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` additionally exposes `raw_limit`/`raw_offset`, `directory_limit`/`directory_offset`, `match_limit`, and `source_max_lines`; its default retains eight match locations per graph result and reports the exact `matches_omitted` remainder. The ranked graph answer stays intact while raw matches and directory summaries page independently. `detect_changes` pages changed files, impacted symbols, and module summaries independently.
 
+Every response is standard UTF-8 without sacrificing POSIX byte-string identities. A value containing malformed UTF-8 is emitted reversibly as `@bytes:<lowercase hex of every original byte>`. A valid 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.
+
 Use `cli <tool> --help` to see the flags generated from that tool's input schema:
 
 ```bash
diff --git a/src/mcp/compact_out.c b/src/mcp/compact_out.c
index 29745b925..81df04fc9 100644
--- a/src/mcp/compact_out.c
+++ b/src/mcp/compact_out.c
@@ -99,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;
@@ -111,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) {
@@ -122,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) {
@@ -132,11 +140,91 @@ static size_t utf8_sequence_length(const unsigned char *p) {
     return 0;
 }
 
+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 (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(const char *s) {
     if (!s || !*s) {
         return false; /* empty cells emit as the "-" placeholder, not quotes */
     }
-    for (const char *p = s; *p; p++) {
+    size_t remaining = strlen(s);
+    for (const char *p = s; *p; p++, remaining--) {
         unsigned char c = (unsigned char)*p;
         /* Space-delimited rows: any internal whitespace or quote forces
          * quoting so column positions stay parseable. Control bytes and
@@ -147,11 +235,12 @@ static bool needs_quotes(const char *s) {
             return true;
         }
         if (c >= 0x80) {
-            size_t len = utf8_sequence_length((const unsigned char *)p);
+            size_t len = utf8_sequence_length((const unsigned char *)p, remaining);
             if (!len) {
                 return true;
             }
             p += len - 1;
+            remaining -= len - 1;
         }
     }
     if (strcmp(s, "true") == 0 || strcmp(s, "false") == 0 || strcmp(s, "null") == 0 ||
@@ -163,7 +252,8 @@ static bool needs_quotes(const char *s) {
 
 static void append_quoted(cbm_sb_t *sb, const char *s) {
     cbm_sb_append_n(sb, "\"", 1);
-    for (const char *p = s ? s : ""; *p; p++) {
+    size_t remaining = s ? strlen(s) : 0;
+    for (const char *p = s ? s : ""; *p; p++, remaining--) {
         switch (*p) {
         case '"':
             cbm_sb_append_n(sb, "\\\"", 2);
@@ -187,14 +277,17 @@ 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);
+                size_t len = utf8_sequence_length((const unsigned char *)p, remaining);
                 if (len) {
                     cbm_sb_append_n(sb, p, len);
                     p += len - 1;
+                    remaining -= len - 1;
                 } 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;
@@ -209,11 +302,19 @@ static void append_value(cbm_sb_t *sb, const char *s) {
         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, strlen(s), &encoded, &encoded_len)) {
+        sb->oom = true;
+        return;
+    }
+    const char *safe = encoded ? encoded : s;
+    if (needs_quotes(safe)) {
+        append_quoted(sb, safe);
     } else {
-        cbm_sb_append(sb, s);
+        cbm_sb_append_n(sb, safe, encoded ? encoded_len : strlen(safe));
     }
+    free(encoded);
 }
 
 /* Object keys and table column names share the compact tree's structural
@@ -222,17 +323,26 @@ static void append_value(cbm_sb_t *sb, const char *s) {
  * empty key must remain the lossless string "" rather than the missing-value
  * placeholder "-". */
 static void append_key(cbm_sb_t *sb, const char *s) {
-    if (!s || !*s || needs_quotes(s) || strpbrk(s, ":()\\")) {
-        append_quoted(sb, s ? s : "");
+    const char *raw = s ? s : "";
+    char *encoded = NULL;
+    size_t encoded_len = 0;
+    if (!cbm_output_encode_text(raw, strlen(raw), &encoded, &encoded_len)) {
+        sb->oom = true;
+        return;
+    }
+    const char *safe = encoded ? encoded : raw;
+    if (!*safe || needs_quotes(safe) || strpbrk(safe, ":()\\")) {
+        append_quoted(sb, safe);
     } else {
-        cbm_sb_append(sb, s);
+        cbm_sb_append_n(sb, safe, encoded ? encoded_len : strlen(safe));
     }
+    free(encoded);
 }
 
 /* ── 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);
@@ -241,14 +351,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);
@@ -262,11 +372,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);
 }
@@ -420,8 +530,8 @@ static size_t tree_semantic_prefix_boundary(const char *text, size_t shared) {
 }
 
 static bool tree_prefix_matches(const char *value, const tree_prefix_candidate_t *candidate) {
-    return value && !needs_quotes(value) && strlen(value) >= candidate->len &&
-           memcmp(value, candidate->text, candidate->len) == 0;
+    return value && !output_text_requires_encoding(value, strlen(value)) && !needs_quotes(value) &&
+           strlen(value) >= candidate->len && memcmp(value, candidate->text, candidate->len) == 0;
 }
 
 static int tree_prefix_choice(const char *value, const tree_prefix_candidate_t *candidates,
@@ -731,7 +841,7 @@ static void json_tree_block_string(cbm_sb_t *sb, const char *text, int depth) {
             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 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;
diff --git a/src/mcp/compact_out.h b/src/mcp/compact_out.h
index 6706e2086..fa86c24e9 100644
--- a/src/mcp/compact_out.h
+++ b/src/mcp/compact_out.h
@@ -33,6 +33,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);
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 0cd032888..26a49872f 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -143,13 +143,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);
 }
 
 /* ══════════════════════════════════════════════════════════════════
@@ -252,7 +309,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;
 }
@@ -265,13 +322,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;
 }
 
@@ -280,6 +347,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);
@@ -287,23 +367,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) {
@@ -331,13 +404,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;
 }
 
@@ -14573,8 +14648,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/tests/test_mcp.c b/tests/test_mcp.c
index 460090c4d..977bdb15f 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -574,12 +574,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 +590,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);
@@ -1449,6 +1457,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));
@@ -14432,7 +14473,7 @@ 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(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);
@@ -14467,6 +14508,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);

From 71d939ad6217a57ed35bc50ab88e82356e02d29b Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 11:41:17 +0200
Subject: [PATCH 07/26] fix(mcp): bind live pagination to snapshots

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md        |   2 +-
 src/mcp/mcp.c    | 304 +++++++++++++++++++++++++++++++++++++++++++++--
 tests/test_mcp.c |  39 ++++++
 3 files changed, 336 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 1eac25eac..c7d89b3ea 100644
--- a/README.md
+++ b/README.md
@@ -580,7 +580,7 @@ When stderr is an interactive terminal, the CLI automatically shows lifecycle an
 
 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 that table is at least 15% and 64 bytes smaller. 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. These are deterministic model-neutral byte savings that normally reduce tokens; 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` additionally exposes `raw_limit`/`raw_offset`, `directory_limit`/`directory_offset`, `match_limit`, and `source_max_lines`; its default retains eight match locations per graph result and reports the exact `matches_omitted` remainder. The ranked graph answer stays intact while raw matches and directory summaries page independently. `detect_changes` pages changed files, impacted symbols, and module summaries independently.
+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` additionally exposes `raw_limit`/`raw_offset`, `directory_limit`/`directory_offset`, `match_limit`, and `source_max_lines`; its default retains eight match locations per graph result and reports the exact `matches_omitted` remainder. The ranked graph answer stays intact while raw matches and directory summaries page independently. `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 without sacrificing POSIX byte-string identities. A value containing malformed UTF-8 is emitted reversibly as `@bytes:<lowercase hex of every original byte>`. A valid 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.
 
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 26a49872f..30bd96d80 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -66,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"
@@ -670,8 +671,7 @@ static const tool_def_t TOOLS[] = {
      "}"},
 
     {"detect_changes", "Detect changes",
-     "Map a Git diff to changed files and transitive graph impact. Sections page independently; "
-     "totals and continuations stay explicit.",
+     "Map a Git diff to files and impact. Page with snapshot cursors.",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},\"scope\":{\"type\":"
      "\"string\",\"enum\":[\"files\",\"impact\"]},"
      "\"direction\":{\"type\":\"string\",\"enum\":[\"inbound\",\"outbound\",\"both\"],\"default\":"
@@ -679,10 +679,13 @@ static const tool_def_t TOOLS[] = {
      "\"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\":\"Approximate token sizing; deterministic ceiling "
      "is 4 UTF-8 bytes per requested token.\"},"
@@ -13039,6 +13042,193 @@ static bool detect_valid_object_id(const char *value) {
     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 void detect_snapshot_add_changed_file(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;
+    }
+    char *absolute = malloc(root_len + relative_len + 2U);
+    if (!absolute) {
+        detect_snapshot_add_field(hash, "path_oom");
+        return;
+    }
+    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};
+    if (cbm_path_info_utf8(absolute, &info) != 0) {
+        detect_snapshot_add_field(hash, "absent");
+        free(absolute);
+        return;
+    }
+    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);
+    if (info.is_regular) {
+        FILE *file = cbm_fopen(absolute, "rb");
+        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);
+            }
+            detect_snapshot_add_field(hash, ferror(file) ? "read_error" : "read_complete");
+            (void)fclose(file);
+        } else {
+            detect_snapshot_add_field(hash, "open_error");
+        }
+    }
+    free(absolute);
+}
+
+static void detect_snapshot_fingerprint(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);
+    for (int i = 0; i < file_count; i++) {
+        detect_snapshot_add_changed_file(&hash, root_path, files[i]);
+    }
+    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);
+        }
+    }
+    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';
+}
+
 static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     char *project = get_project_arg(args);
     char *base_branch = cbm_mcp_get_string_arg(args, "base_branch");
@@ -13465,6 +13655,11 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     } 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;
@@ -13558,12 +13753,6 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
                                   MCP_BFS_LIMIT_MAX, &impact, &truncated);
     }
 
-    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;
-    }
-
     detect_module_row_t *modules = NULL;
     int nmods = 0;
     int module_overflow = 0;
@@ -13577,6 +13766,76 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
      * 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);
+    char generation[96] = "unknown";
+    (void)cbm_store_generation(store, generation, sizeof(generation));
+    char detect_snapshot[33];
+    detect_snapshot_fingerprint(root_path, head_oid, base_oid, merge_base, generation, files,
+                                file_count, &impact, modules, nmods, module_overflow,
+                                detect_snapshot);
+
+    const char *cursor_error = NULL;
+    detect_cursor_t decoded_cursor = {0};
+    if (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 (!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 (!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;
+            }
+        }
+    }
+    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);
+    }
+
+    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) {
@@ -13617,6 +13876,10 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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);
+            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"
@@ -13643,6 +13906,12 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         cbm_tree_scalar_int(&sb, "seed_symbols", seed_count);
         if (want_symbols) {
             detect_emit_impacted_tree(&sb, &impact, imp_start, imp_returned, truncated);
+            if (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);
@@ -13652,6 +13921,10 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             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);
+                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
@@ -13716,6 +13989,10 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         if (changed_has_more && changed_returned > 0) {
             yyjson_mut_obj_add_int(doc, root_obj, "changed_next_offset",
                                    changed_start + changed_returned);
+            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
@@ -13751,6 +14028,10 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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);
+            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);
@@ -13766,6 +14047,10 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             if (module_has_more && module_returned > 0) {
                 yyjson_mut_obj_add_int(doc, root_obj, "module_next_offset",
                                        module_start + module_returned);
+                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);
             } else if (module_has_more) {
                 yyjson_mut_obj_add_bool(doc, root_obj,
                                         module_limit == 0
@@ -13855,6 +14140,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     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);
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 977bdb15f..b6a9209f9 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -10445,6 +10445,10 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     ASSERT_TRUE(yyjson_get_bool(yyjson_obj_get(root, "changed_has_more")));
     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);
@@ -10468,6 +10472,7 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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")), 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);
@@ -10477,6 +10482,7 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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);
@@ -10599,6 +10605,39 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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")));
+    yyjson_doc_free(doc);
+    free(inner);
+    free(response);
+
+    /* 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);
+    free(changed_cursor);
+
     cbm_mcp_server_free(srv);
     free(long_detect_file);
     free(long_detect_qn);

From 63255fbfd1d9203b984e17642c93e3310023e979 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 11:43:17 +0200
Subject: [PATCH 08/26] feat(cli): add explicit quiet output mode

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md               |   4 +-
 src/cli/progress_sink.c |  65 ++++++++++++++++++++-
 src/cli/progress_sink.h |  21 ++++++-
 src/main.c              | 121 ++++++++++++++++++++++-----------------
 tests/test_cli.c        | 124 +++++++++++++++++++++++++++++++++++++++-
 5 files changed, 275 insertions(+), 60 deletions(-)

diff --git a/README.md b/README.md
index c7d89b3ea..95bee4ff5 100644
--- a/README.md
+++ b/README.md
@@ -576,7 +576,7 @@ 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. 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.
+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 that table is at least 15% and 64 bytes smaller. 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. These are deterministic model-neutral byte savings that normally reduce tokens; exact token counts still depend on the caller's tokenizer.
 
@@ -597,6 +597,8 @@ 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
+# 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'
 ```
diff --git a/src/cli/progress_sink.c b/src/cli/progress_sink.c
index f21c87f9f..d994c8a81 100644
--- a/src/cli/progress_sink.c
+++ b/src/cli/progress_sink.c
@@ -50,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]) {
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/main.c b/src/main.c
index 19ffcef63..6c5273060 100644
--- a/src/main.c
+++ b/src/main.c
@@ -6,6 +6,7 @@
  *   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)
@@ -534,10 +535,12 @@ static bool client_start_parent_watchdog(pid_t initial_ppid) {
 
 /* ── CLI mode ───────────────────────────────────────────────────── */
 
-#define CLI_USAGE                                                                                \
-    "Usage: codebase-memory-mcp cli [--progress] [--verbose] [--json] <tool_name> [json_args]\n" \
-    "  --progress  Show lifecycle progress even when stderr is redirected\n"                     \
-    "  --verbose   Include informational logs (preserves CBM_LOG_LEVEL=debug)\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.
@@ -586,24 +589,6 @@ static bool cli_strip_flag(int *argc, char **argv, const char *flag) {
     return false;
 }
 
-/* Outer CLI flags precede the tool name. Keep this distinct from
- * cli_strip_flag(): several MCP tools have their own `verbose` input, so
- * `cli index_status --verbose` must remain a tool argument while
- * `cli --verbose index_status` configures process logging. */
-static bool cli_strip_outer_flag(int *argc, char **argv, const char *flag) {
-    for (int i = 0; i < *argc && argv[i] && argv[i][0] == '-'; i++) {
-        if (strcmp(argv[i], flag) != 0) {
-            continue;
-        }
-        for (int j = i; j < *argc - SKIP_ONE; j++) {
-            argv[j] = argv[j + SKIP_ONE];
-        }
-        (*argc)--;
-        return true;
-    }
-    return false;
-}
-
 /* Strip a flag AND its following value from argv, returning the value (a pointer
  * into the original argv strings, valid for the process lifetime) or NULL if the
  * flag is absent. */
@@ -682,14 +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) {
-    bool verbose_requested = cli_strip_outer_flag(&argc, argv, "--verbose");
-    if (verbose_requested && cbm_log_get_level() > CBM_LOG_INFO) {
-        cbm_log_set_level(CBM_LOG_INFO);
+    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;
@@ -699,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
@@ -767,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 ... */
@@ -796,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);
@@ -816,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) {
@@ -917,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] [--verbose] [--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");
@@ -926,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");
@@ -1302,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,
@@ -1515,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;
@@ -1527,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,
@@ -1548,7 +1560,8 @@ 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) {
+static char *main_local_cli_daemon_execute(const char *tool_name, const char *args_json,
+                                           bool quiet_requested) {
     cbm_daemon_ipc_endpoint_t *endpoint = cbm_daemon_bootstrap_endpoint_new(NULL);
     char executable_path[MAIN_PATH_CAP] = {0};
     cbm_daemon_build_identity_t identity;
@@ -1570,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",
@@ -2337,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
@@ -2429,6 +2443,11 @@ int main(int argc, char **argv) {
      * 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 &&
@@ -2867,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/tests/test_cli.c b/tests/test_cli.c
index 64118c1c8..dfeaf7849 100644
--- a/tests/test_cli.c
+++ b/tests/test_cli.c
@@ -55,9 +55,123 @@ int cbm_cli_activation_abort_cleanup_probe_for_test(void);
 bool cbm_cli_activation_test_ops_installed(void);
 
 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();
 }
 
@@ -12580,6 +12694,10 @@ TEST(cli_windows_update_hands_off_to_install_script) {
 
 SUITE(cli) {
     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);

From 733e463186a502b3e88f7f99ce927f7c84b6fc35 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 11:47:16 +0200
Subject: [PATCH 09/26] fix(mcp): make search code pagination lossless

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md        |   2 +-
 src/mcp/mcp.c    | 506 ++++++++++++++++++++++++++++++++++++-----------
 tests/test_mcp.c | 347 ++++++++++++++++++++++++++++++++
 3 files changed, 740 insertions(+), 115 deletions(-)

diff --git a/README.md b/README.md
index 95bee4ff5..4ab937750 100644
--- a/README.md
+++ b/README.md
@@ -580,7 +580,7 @@ When stderr is an interactive terminal, the CLI automatically shows lifecycle an
 
 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 that table is at least 15% and 64 bytes smaller. 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. These are deterministic model-neutral byte savings that normally reduce tokens; 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` additionally exposes `raw_limit`/`raw_offset`, `directory_limit`/`directory_offset`, `match_limit`, and `source_max_lines`; its default retains eight match locations per graph result and reports the exact `matches_omitted` remainder. The ranked graph answer stays intact while raw matches and directory summaries page independently. `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.
+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 without sacrificing POSIX byte-string identities. A value containing malformed UTF-8 is emitted reversibly as `@bytes:<lowercase hex of every original byte>`. A valid 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.
 
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 30bd96d80..b82a91e66 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -607,20 +607,21 @@ static const tool_def_t TOOLS[] = {
      "\"enum\":[\"compact\",\"full\",\"files\"],\"default\":\"compact\"},"
      "\"context\":{\"type\":\"integer\"},"
      "\"regex\":{\"type\":\"boolean\",\"default\":false},\"limit\":{\"type\":\"integer\","
-     "\"default\":10,\"minimum\":1,\"maximum\":500,\"description\":\"Ranked graph rows.\"},"
-     "\"raw_limit\":{\"type\":\"integer\",\"default\":5,\"minimum\":0,\"maximum\":100,"
-     "\"description\":\"Unclassified grep rows; set 0 to omit.\"},"
+     "\"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 a match-centered preview.\"},"
      "\"directory_limit\":{\"type\":\"integer\",\"default\":20,\"minimum\":0,"
-     "\"maximum\":64,\"description\":\"Directory summary rows; set 0 to omit.\"},"
+     "\"maximum\":64},"
      "\"directory_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
      "\"match_limit\":{\"type\":\"integer\",\"default\":8,\"minimum\":1,"
-     "\"maximum\":500,\"description\":\"Locations per row; exact remainder in matches_omitted.\"},"
+     "\"maximum\":500},"
      "\"source_max_lines\":{\"type\":\"integer\",\"default\":20,\"minimum\":1,"
-     "\"maximum\":200,\"description\":\"Per-result source window in full mode.\"},"
-     "\"max_output_tokens\":{\"type\":\"integer\",\"minimum\":128,\"maximum\":1000000,"
-     "\"description\":\"Approximate sizing; hard cap 4 UTF-8 bytes/token. Diagnostics yield "
-     "before graph rows.\"},"
+     "\"maximum\":200},"
+     "\"max_output_tokens\":{\"type\":\"integer\",\"minimum\":128,\"maximum\":1000000},"
      "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
      "\"required\":[\"pattern\",\"project\"]}"},
 
@@ -10672,6 +10673,12 @@ typedef struct {
     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;
 
@@ -10856,8 +10863,8 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
 
 /* 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_start,
-                                               int raw_count) {
+                                               int result_start, int output_count,
+                                               grep_match_t *raw, int raw_start, int raw_count) {
     yyjson_mut_val *files_arr = yyjson_mut_arr(doc);
     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;
@@ -10867,16 +10874,17 @@ static yyjson_mut_val *build_dedup_files_array(yyjson_mut_doc *doc, search_resul
     }
     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_files[seen_count++] = sr[fi].file;
-            yyjson_mut_arr_add_str(doc, files_arr, sr[fi].file);
+            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; fi++) {
@@ -11032,6 +11040,19 @@ static int count_truncated_raw_content(const grep_match_t *raw, int raw_count) {
     return count;
 }
 
+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 int search_match_lines_shown(const search_result_t *result, int match_limit) {
     return result->match_count < match_limit ? result->match_count : match_limit;
 }
@@ -11062,12 +11083,13 @@ static char *search_match_lines_text(const search_result_t *result, int match_li
  * 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 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) {
+                                         int raw_count, 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);
@@ -11092,7 +11114,7 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
         return NULL;
     }
     for (int ri = 0; ri < output_count; ri++) {
-        search_result_t *r = &sr[ri];
+        search_result_t *r = &sr[result_start + ri];
         if (r->start_line > 0) {
             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);
@@ -11136,27 +11158,61 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
     free(rendered);
 
     if (raw_output > 0) {
-        static const char *const rcols[] = {"file", "line", "content"};
-        const char **raw_cells = calloc((size_t)raw_output * 3U, sizeof(*raw_cells));
-        char (*line_text)[CBM_SZ_32] = calloc((size_t)raw_output, sizeof(*line_text));
-        if (!raw_cells || !line_text) {
-            free(line_text);
+        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 = raw_start + ri;
-            snprintf(line_text[ri], sizeof(line_text[ri]), "%d", raw[raw_index].line);
-            raw_cells[(size_t)ri * 3U] = raw[raw_index].file;
-            raw_cells[(size_t)ri * 3U + 1U] = line_text[ri];
-            raw_cells[(size_t)ri * 3U + 2U] = raw[raw_index].content;
-        }
-        static const bool raw_string_cols[] = {true, false, true};
-        static const bool raw_prefix_cols[] = {true, false, false};
-        cbm_tree_table_rows_profiled(&sb, "raw", raw_output, rcols, 3, raw_cells, raw_string_cols,
-                                     raw_prefix_cols);
-        free(line_text);
+            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);
     }
 
@@ -11203,9 +11259,18 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
     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 = output_count < sr_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);
@@ -11262,9 +11327,10 @@ 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 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 raw_count, 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) {
@@ -11275,8 +11341,8 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
     yyjson_mut_doc_set_root(doc, root_obj);
 
     if (mode == MODE_FILES) {
-        yyjson_mut_val *files =
-            build_dedup_files_array(doc, sr, output_count, raw, raw_start, raw_output);
+        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;
@@ -11299,7 +11365,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,
@@ -11335,6 +11401,14 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
         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);
         for (int ri = 0; ri < raw_output; ri++) {
@@ -11343,6 +11417,25 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
             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);
@@ -11376,9 +11469,18 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
     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 = output_count < sr_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);
@@ -11464,24 +11566,25 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
  * 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 gm_count, 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 raw_count, 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, gm_count, 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);
+        return assemble_search_output_toon(
+            sr, sr_count, raw, raw_count, 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, gm_count, 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);
+    char *json = assemble_search_output(
+        sr, sr_count, raw, raw_count, 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;
     }
@@ -11521,9 +11624,9 @@ char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
         initialized++;
     }
     char *payload =
-        render_search_payload(results, row_count, NULL, 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);
+        render_search_payload(results, row_count, NULL, 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;
 }
@@ -11532,8 +11635,13 @@ char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
 /* 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, bool scan_saturated,
-                                 bool json_format, int max_output_tokens) {
+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) {
+    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);
@@ -11544,8 +11652,36 @@ static char *search_budget_floor(int sr_count, int raw_count, int gm_count, bool
         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", 0);
-        cbm_tree_scalar_bool(&sb, "has_more", sr_count > 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_returned", 0);
+        cbm_tree_scalar_bool(&sb, "raw_has_more", raw_has_more);
+        if (raw_has_more) {
+            cbm_tree_scalar_bool(&sb,
+                                 raw_limit == 0 ? "raw_continuation_requires_positive_limit"
+                                                : "raw_continuation_requires_higher_budget",
+                                 true);
+        }
+        cbm_tree_scalar_int(&sb, "directories_total", directory_total);
+        cbm_tree_scalar_int(&sb, "directories_returned", 0);
+        cbm_tree_scalar_bool(&sb, "directories_has_more", directories_has_more);
+        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", true);
         cbm_tree_scalar_str(&sb, "truncation_reason", "output_budget");
         cbm_tree_scalar_int(&sb, "max_output_tokens", max_output_tokens);
@@ -11561,8 +11697,36 @@ static char *search_budget_floor(int sr_count, int raw_count, int gm_count, bool
     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_str(doc, root, "total_relation", scan_saturated ? "gte" : "eq");
+    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", sr_count > 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_returned", 0);
+    yyjson_mut_obj_add_bool(doc, root, "raw_has_more", raw_has_more);
+    if (raw_has_more) {
+        yyjson_mut_obj_add_bool(doc, root,
+                                raw_limit == 0 ? "raw_continuation_requires_positive_limit"
+                                               : "raw_continuation_requires_higher_budget",
+                                true);
+    }
+    yyjson_mut_obj_add_int(doc, root, "directories_total", directory_total);
+    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) {
+        yyjson_mut_obj_add_bool(doc, root,
+                                directory_limit == 0
+                                    ? "directory_continuation_requires_positive_limit"
+                                    : "directory_continuation_requires_higher_budget",
+                                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");
     yyjson_mut_obj_add_int(doc, root, "max_output_tokens", max_output_tokens);
@@ -11597,8 +11761,92 @@ static int grep_match_cmp(const void *left, const void *right) {
     return (a->line > b->line) - (a->line < b->line);
 }
 
+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;
+}
+
+static bool search_utf8_continuation_byte(unsigned char byte) {
+    return (byte & 0xC0U) == 0x80U;
+}
+
+/* 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. Both boundaries are
+ * adjusted to UTF-8 code-point boundaries and the adjusted start is reported. */
+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;
+            }
+        }
+    }
+    while (start < total && search_utf8_continuation_byte((unsigned char)content[start])) {
+        start++;
+    }
+
+    size_t remaining = total - start;
+    size_t returned = remaining < preview_capacity ? remaining : preview_capacity;
+    size_t end = start + returned;
+    if (end < total) {
+        while (end > start && end < total &&
+               search_utf8_continuation_byte((unsigned char)content[end])) {
+            end--;
+        }
+    }
+    returned = end - start;
+    memcpy(match->content, content + start, returned);
+    match->content[returned] = '\0';
+    sanitize_utf8_inplace(match->content);
+    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;
+}
+
 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,
+                                          const char *pattern, bool use_regex,
+                                          bool raw_content_offset_set, size_t raw_content_offset,
                                           int grep_limit, int *out_count, bool *out_saturated,
                                           bool *out_oom) {
     int gm_cap = CBM_SZ_64;
@@ -11606,6 +11854,8 @@ static grep_match_t *collect_grep_matches(FILE *fp, const char *root_path, size_
     grep_match_t *gm = calloc((size_t)gm_cap, sizeof(*gm));
     char *line = NULL;
     size_t line_capacity = 0;
+    cbm_regex_t content_regex;
+    bool content_regex_ready = false;
 
     if (out_saturated) {
         *out_saturated = false;
@@ -11617,6 +11867,8 @@ static grep_match_t *collect_grep_matches(FILE *fp, const char *root_path, size_
         *out_count = 0;
         return NULL;
     }
+    content_regex_ready = use_regex && pattern &&
+                          cbm_regcomp(&content_regex, pattern, CBM_REG_EXTENDED) == CBM_REG_OK;
     for (;;) {
         ssize_t line_length = cbm_getline(&line, &line_capacity, fp);
         if (line_length < 0) {
@@ -11690,19 +11942,20 @@ static grep_match_t *collect_grep_matches(FILE *fp, const char *root_path, size_
         }
         gm[gm_count].line = (int)strtol(sep1 + SKIP_ONE, NULL, CBM_DECIMAL_BASE);
         const char *content = sep2 + SKIP_ONE;
-        size_t content_length = strlen(content);
-        gm[gm_count].content_truncated = content_length >= sizeof(gm[gm_count].content);
-        size_t content_copy = content_length;
-        if (content_copy >= sizeof(gm[gm_count].content)) {
-            content_copy = sizeof(gm[gm_count].content) - SKIP_ONE;
-        }
-        memcpy(gm[gm_count].content, content, content_copy);
-        gm[gm_count].content[content_copy] = '\0';
-        sanitize_utf8_inplace(gm[gm_count].content);
+        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(&gm[gm_count], content, raw_content_offset_set, raw_content_offset,
+                           match_known, match_start, match_end);
         gm_count++;
     }
 
     free(line);
+    if (content_regex_ready) {
+        cbm_regfree(&content_regex);
+    }
     if (out_oom && *out_oom) {
         free_grep_matches(gm, gm_count);
         *out_count = 0;
@@ -12143,15 +12396,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();
@@ -12162,10 +12417,13 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     int mode = parse_search_mode(mode_str);
     free(mode_str);
 
-    if (limit < 1) {
-        limit = 1;
-    } else if (limit > 500) {
-        limit = 500;
+    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) {
@@ -12177,6 +12435,19 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     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;
@@ -12376,7 +12647,9 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         }
 
         gm = collect_grep_matches(fp, root_path, strlen(root_path), has_path_filter, &path_regex,
-                                  grep_limit, &gm_count, &scan_saturated, &grep_oom);
+                                  pattern, use_regex, raw_content_offset_set,
+                                  (size_t)raw_content_offset_arg, grep_limit, &gm_count,
+                                  &scan_saturated, &grep_oom);
         cbm_pclose(fp);
         /* 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. */
@@ -12478,7 +12751,11 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     bool sc_legacy_json = sc_format && strcmp(sc_format, "json") == 0;
     free(sc_format);
 
-    int output_count = sr_count < limit ? sr_count : limit;
+    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_count - raw_start;
     if (raw_output > raw_limit) {
@@ -12508,18 +12785,18 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     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, gm_count, 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);
+        sr, sr_count, raw, raw_count, 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, gm_count, 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);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, 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
@@ -12527,20 +12804,20 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     while (payload && strlen(payload) > byte_budget && raw_output > 0) {
         raw_output--;
         free(payload);
-        payload = render_search_payload(sr, sr_count, raw, raw_count, gm_count, 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);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, 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, gm_count, 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);
+        payload = render_search_payload(
+            sr, sr_count, raw, raw_count, 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
@@ -12553,10 +12830,10 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         while (low <= high) {
             int middle = low + (high - low) / 2;
             char *candidate = render_search_payload(
-                sr, sr_count, raw, raw_count, gm_count, 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);
+                sr, sr_count, raw, raw_count, 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;
@@ -12574,10 +12851,10 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         } else {
             source_max_lines = 0;
             payload = render_search_payload(
-                sr, sr_count, raw, raw_count, gm_count, 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);
+                sr, sr_count, raw, raw_count, 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);
         }
     }
 
@@ -12589,10 +12866,10 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         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, gm_count, 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);
+                sr, sr_count, raw, raw_count, 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;
@@ -12605,8 +12882,9 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
 
     if (!payload || strlen(payload) > byte_budget) {
         free(payload);
-        payload = search_budget_floor(sr_count, raw_count, gm_count, scan_saturated, sc_legacy_json,
-                                      max_output_tokens);
+        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);
     }
     char *result = cbm_mcp_text_result(payload ? payload : "out of memory", payload == NULL);
     free(payload);
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index b6a9209f9..61cf2de45 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -6697,6 +6697,40 @@ TEST(tool_search_code_limit_declares_a_minimum_issue1511) {
     PASS();
 }
 
+TEST(tool_search_code_declares_independent_result_and_raw_content_paging) {
+    cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+    char *resp = cbm_mcp_server_handle(
+        srv, "{\"jsonrpc\":\"2.0\",\"id\":37,\"method\":\"tools/list\",\"params\":{}}");
+    ASSERT_NOT_NULL(resp);
+
+    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();
+}
+
 TEST(tool_search_code_no_project) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
 
@@ -7015,6 +7049,99 @@ TEST(search_code_raw_and_directory_remainders_are_independently_pageable) {
     PASS();
 }
 
+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);
+    }
+
+    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);
+
+    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();
+}
+
 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);
@@ -7039,6 +7166,109 @@ static char *search_code_long_identity(char fill, bool path) {
     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 *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(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)};
@@ -7148,6 +7378,119 @@ TEST(search_code_long_raw_line_is_one_truthfully_truncated_match) {
     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);
+
+    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-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);
+
+    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 *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(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,\"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(search_code_match_locations_are_explicitly_bounded_and_expandable) {
     char tmp[256];
     snprintf(tmp, sizeof(tmp), "/tmp/cbm_srch_match_locations_XXXXXX");
@@ -14671,14 +15014,18 @@ 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_reports_scan_saturation);
     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_match_locations_are_explicitly_bounded_and_expandable);
     RUN_TEST(search_code_scoped_path_with_spaces_issue687);
 #ifdef _WIN32

From ad8fd6ffab036e5caea6330ec8e2ba5e24409848 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 11:51:08 +0200
Subject: [PATCH 10/26] feat(mcp): add lossless semantic pagination

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md         |   2 +-
 src/mcp/mcp.c     | 184 ++++++++++++++++++------
 src/store/store.c | 108 ++++++++------
 tests/test_mcp.c  | 350 ++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 558 insertions(+), 86 deletions(-)

diff --git a/README.md b/README.md
index 4ab937750..88396fd74 100644
--- a/README.md
+++ b/README.md
@@ -620,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). |
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index b82a91e66..8fd808f7d 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -473,10 +473,8 @@ static const tool_def_t TOOLS[] = {
      "},\"required\":[\"repo_path\"]}"},
 
     {"search_graph", "Search graph",
-     "Search: BM25 query, regex name/qn, or vector semantic_query. Regex rows keep "
-     "qn/file/lines and in/out over CALLS, USAGE, CALL_REFERENCE, INHERITS, IMPLEMENTS. "
-     "Defaults: the smaller lossless direct/grouped tree, limit 50, ~3200 tokens (4x byte cap). "
-     "Page with offset; detail=ids is qn-only.",
+     "Regex rows keep qn/file/lines and in/out over CALLS/USAGE/CALL_REFERENCE/INHERITS/"
+     "IMPLEMENTS. Pages: offset/limit structural; semantic_offset/semantic_limit semantic.",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},"
      "\"query\":{\"type\":\"string\"},"
      "\"label\":{\"type\":\"string\"},\"name_pattern\":{\"type\":\"string\"},\"qn_pattern\":{"
@@ -484,7 +482,12 @@ static const tool_def_t TOOLS[] = {
      "\"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\"}},\"limit\":{\"type\":"
+     "\"type\":\"array\",\"items\":{\"type\":\"string\"}},"
+     "\"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,"
@@ -3625,8 +3628,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;
@@ -3647,9 +3650,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;
@@ -3766,13 +3768,23 @@ typedef struct {
     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 total > offset + 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) {
+                                size_t max_output_bytes, bool continuation_supported,
+                                bool continuation_requires_positive_limit) {
     bool has_more = continuation_supported && sg_page_has_more(total, offset, plan->returned);
     cbm_tree_scalar_int(sb, "total", total);
     cbm_tree_scalar_int(sb, "returned", plan->returned);
@@ -3780,7 +3792,11 @@ static void sg_emit_paging_tree(cbm_sb_t *sb, int total, int offset, const sg_re
     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_higher_budget", true);
+        cbm_tree_scalar_bool(sb,
+                             continuation_requires_positive_limit
+                                 ? "continuation_requires_positive_limit"
+                                 : "continuation_requires_higher_budget",
+                             true);
     }
     bool truncated = has_more || plan->budget_hit;
     cbm_tree_scalar_bool(sb, "truncated", truncated);
@@ -3808,7 +3824,8 @@ static void sg_emit_paging_tree(cbm_sb_t *sb, int total, int offset, const sg_re
 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_supported,
+                                bool continuation_requires_positive_limit) {
     bool has_more = continuation_supported && sg_page_has_more(total, offset, plan->returned);
     yyjson_mut_obj_add_int(doc, root, "total", total);
     yyjson_mut_obj_add_int(doc, root, "returned", plan->returned);
@@ -3817,7 +3834,11 @@ static void sg_emit_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int t
     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_higher_budget", true);
+        yyjson_mut_obj_add_bool(doc, root,
+                                continuation_requires_positive_limit
+                                    ? "continuation_requires_positive_limit"
+                                    : "continuation_requires_higher_budget",
+                                true);
     }
     bool truncated = has_more || plan->budget_hit;
     yyjson_mut_obj_add_bool(doc, root, "truncated", truncated);
@@ -3843,6 +3864,46 @@ static void sg_emit_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int t
     }
 }
 
+static bool sg_semantic_has_more(const sg_semantic_page_t *semantic, int returned) {
+    return semantic && sg_page_has_more(semantic->total, semantic->offset, returned);
+}
+
+static void sg_emit_semantic_paging_tree(cbm_sb_t *sb, const sg_semantic_page_t *semantic,
+                                         int 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 ? "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);
+    }
+}
+
+static void sg_emit_semantic_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *root,
+                                         const sg_semantic_page_t *semantic, int 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 ? "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);
+    }
+}
+
 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"};
@@ -4137,12 +4198,12 @@ 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 cbm_vector_result_t *vresults, int semantic_total,
-                               bool semantic_only, const char *diagnostic_hint,
-                               const sg_render_plan_t *plan, size_t max_output_bytes) {
+                               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 ? 0 : offset;
+    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;
     }
@@ -4158,16 +4219,16 @@ static char *sg_render_payload(bool json_format, const cbm_search_output_t *out,
                                          relationship, plan->connected_returned, plan->returned);
             }
         }
-        if (semantic_total > 0 || semantic_only) {
-            cbm_tree_scalar_int(&sb, "semantic_total", semantic_total);
-            cbm_tree_scalar_int(&sb, "semantic_returned", plan->semantic_returned);
-            emit_semantic_results_toon(&sb, vresults, plan->semantic_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, !semantic_only);
+                            connected_requested, max_output_bytes, true,
+                            semantic_only && semantic->limit == 0);
         return cbm_sb_finish(&sb);
     }
 
@@ -4182,23 +4243,24 @@ static char *sg_render_payload(bool json_format, const cbm_search_output_t *out,
                                           relationship, plan->connected_returned, plan->returned);
         }
     }
-    if (semantic_total > 0 || semantic_only) {
-        yyjson_mut_obj_add_int(doc, root, "semantic_total", semantic_total);
-        yyjson_mut_obj_add_int(doc, root, "semantic_returned", plan->semantic_returned);
-        emit_semantic_results(doc, root, vresults, plan->semantic_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, !semantic_only);
+                        connected_requested, 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 *sg_budget_floor(bool json_format, int total, int offset, int semantic_total,
-                             size_t max_output_bytes, bool semantic_only) {
+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,
@@ -4208,20 +4270,26 @@ static char *sg_budget_floor(bool json_format, int total, int offset, int semant
         .budget_hit = true,
         .floor_exceeded = true,
     };
-    int page_total = total > 0 ? total : semantic_total;
-    int page_offset = total > 0 ? offset : 0;
+    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);
-        sg_emit_paging_tree(&sb, page_total, page_offset, &floor, 0, false, max_output_bytes,
-                            !semantic_only);
+        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,
-                        !semantic_only);
+                        true, semantic_only && semantic->limit == 0);
     char *json = yy_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
     return json;
@@ -4260,6 +4328,22 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     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) {
+        semantic_offset = MCP_QUERY_MAX_VISIBLE_ROWS;
+    }
+    /* 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;
@@ -4335,8 +4419,8 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     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);
+    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);
@@ -4355,6 +4439,18 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
             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 ||
@@ -4385,7 +4481,7 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     sg_render_plan_t plan = {
         .returned = out.count,
         .fields_returned = requested_fields,
-        .semantic_returned = vcount,
+        .semantic_returned = semantic_page_count,
         .connected_returned = !detail_ids && include_connected,
         .core_hint_returned = diagnostic_hint != NULL,
         .budget_hit = false,
@@ -4396,8 +4492,8 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     for (;;) {
         payload =
             sg_render_payload(json_format, &out, offset, fields, requested_fields, store,
-                              relationship, !detail_ids && include_connected, detail_ids, vresults,
-                              vcount, semantic_only, diagnostic_hint, &plan, max_output_bytes);
+                              relationship, !detail_ids && include_connected, detail_ids, &semantic,
+                              semantic_only, diagnostic_hint, &plan, max_output_bytes);
         if (!payload || strlen(payload) <= max_output_bytes) {
             break;
         }
@@ -4423,12 +4519,12 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
         }
     }
 
-    bool identity_available = out.count > 0 || vcount > 0;
+    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, vcount, max_output_bytes,
+        payload = sg_budget_floor(json_format, out.total, offset, &semantic, max_output_bytes,
                                   semantic_only);
     }
 
diff --git a/src/store/store.c b/src/store/store.c
index 24f20ed62..d2b4d19ad 100644
--- a/src/store/store.c
+++ b/src/store/store.c
@@ -8504,6 +8504,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) {
@@ -8519,16 +8531,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;
@@ -8538,59 +8549,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/tests/test_mcp.c b/tests/test_mcp.c
index 61cf2de45..cbe39eaf5 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -3181,6 +3181,355 @@ TEST(tool_search_graph_bm25_reports_candidate_saturation) {
     PASS();
 }
 
+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 *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 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);
+    }
+
+    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);
+    }
+
+    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_search_graph_budget_preserves_long_values_and_continuation) {
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
@@ -14956,6 +15305,7 @@ SUITE(mcp) {
     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_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);

From c9ed21891b0fc7883f105f2041353b300eee8c93 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 12:25:02 +0200
Subject: [PATCH 11/26] fix(mcp): fail closed on incomplete snapshots

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/mcp.c          | 134 +++++++++++++++++++++++++++++++----------
 src/mcp/mcp_internal.h |   8 +++
 tests/test_mcp.c       |  60 ++++++++++++++++++
 3 files changed, 170 insertions(+), 32 deletions(-)

diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 8fd808f7d..b53d4b30b 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -1607,6 +1607,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 */
 
@@ -1905,6 +1909,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. */
@@ -13510,19 +13526,19 @@ static void detect_snapshot_add_field(cbm_sha256_ctx *hash, const char *value) {
     cbm_sha256_update(hash, "|", 1);
 }
 
-static void detect_snapshot_add_changed_file(cbm_sha256_ctx *hash, const char *root_path,
-                                             const char *relative_path) {
+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;
+        return false;
     }
     char *absolute = malloc(root_len + relative_len + 2U);
     if (!absolute) {
         detect_snapshot_add_field(hash, "path_oom");
-        return;
+        return false;
     }
     memcpy(absolute, root_path, root_len);
     absolute[root_len] = '/';
@@ -13530,33 +13546,59 @@ static void detect_snapshot_add_changed_file(cbm_sha256_ctx *hash, const char *r
 
     cbm_path_info_t info = {0};
     if (cbm_path_info_utf8(absolute, &info) != 0) {
-        detect_snapshot_add_field(hash, "absent");
+        /* A missing path can be a legitimate deletion, but the portable
+         * metadata API cannot distinguish it from permission and transient
+         * inspection failures on every supported platform. Hash the observed
+         * 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;
+        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 = cbm_fopen(absolute, "rb");
+        bool allow_open = true;
+#ifdef CBM_ENABLE_TEST_SEAMS
+        if (srv && srv->snapshot_read_test_hook) {
+            allow_open = srv->snapshot_read_test_hook(srv->snapshot_read_test_context, absolute);
+        }
+#else
+        (void)srv;
+#endif
+        FILE *file = allow_open ? cbm_fopen(absolute, "rb") : NULL;
         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);
             }
-            detect_snapshot_add_field(hash, ferror(file) ? "read_error" : "read_complete");
+            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 void detect_snapshot_fingerprint(const char *root_path, const char *head_oid,
+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,
@@ -13569,8 +13611,11 @@ static void detect_snapshot_fingerprint(const char *root_path, const char *head_
     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++) {
-        detect_snapshot_add_changed_file(&hash, root_path, files[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++) {
@@ -13601,6 +13646,7 @@ static void detect_snapshot_fingerprint(const char *root_path, const char *head_
         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) {
@@ -14143,13 +14189,20 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     char generation[96] = "unknown";
     (void)cbm_store_generation(store, generation, sizeof(generation));
     char detect_snapshot[33];
-    detect_snapshot_fingerprint(root_path, head_oid, base_oid, merge_base, generation, files,
-                                file_count, &impact, modules, nmods, module_overflow,
-                                detect_snapshot);
+    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);
 
     const char *cursor_error = NULL;
     detect_cursor_t decoded_cursor = {0};
-    if (changed_cursor_arg && changed_cursor_arg[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";
@@ -14242,6 +14295,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         if (output_budget_floor_exceeded) {
             cbm_tree_scalar_bool(&sb, "output_budget_floor_exceeded", 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);
@@ -14251,9 +14307,11 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         if (changed_has_more && changed_returned > 0) {
             cbm_tree_scalar_int(&sb, "changed_next_offset", changed_start + changed_returned);
             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);
+            if (detect_snapshot_complete) {
+                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"
@@ -14280,7 +14338,8 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         cbm_tree_scalar_int(&sb, "seed_symbols", seed_count);
         if (want_symbols) {
             detect_emit_impacted_tree(&sb, &impact, imp_start, imp_returned, truncated);
-            if (imp_start + imp_returned < impact.visited_count && imp_returned > 0) {
+            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);
@@ -14296,9 +14355,11 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             if (module_has_more && module_returned > 0) {
                 cbm_tree_scalar_int(&sb, "module_next_offset", module_start + module_returned);
                 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);
+                if (detect_snapshot_complete) {
+                    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
@@ -14356,6 +14417,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         if (output_budget_floor_exceeded) {
             yyjson_mut_obj_add_bool(doc, root_obj, "output_budget_floor_exceeded", 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);
         bool changed_has_more = changed_start + changed_returned < file_count;
@@ -14364,9 +14428,11 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             yyjson_mut_obj_add_int(doc, root_obj, "changed_next_offset",
                                    changed_start + changed_returned);
             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);
+            if (detect_snapshot_complete) {
+                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
@@ -14402,10 +14468,12 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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);
-            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);
+            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);
@@ -14421,10 +14489,12 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             if (module_has_more && module_returned > 0) {
                 yyjson_mut_obj_add_int(doc, root_obj, "module_next_offset",
                                        module_start + module_returned);
-                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 (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);
+                }
             } else if (module_has_more) {
                 yyjson_mut_obj_add_bool(doc, root_obj,
                                         module_limit == 0
diff --git a/src/mcp/mcp_internal.h b/src/mcp/mcp_internal.h
index a7dd66935..70660f5f1 100644
--- a/src/mcp/mcp_internal.h
+++ b/src/mcp/mcp_internal.h
@@ -50,6 +50,14 @@ bool cbm_detect_node_in_hunks(const cbm_node_t *node, const cbm_changed_hunk_t *
                               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. */
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index cbe39eaf5..5007e0226 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;
@@ -11315,6 +11320,37 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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. */
@@ -11328,6 +11364,30 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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);
+#endif
     free(changed_cursor);
 
     cbm_mcp_server_free(srv);

From f6f09542cb9f56e25c09d713a6e4116ec23d4f27 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 12:36:51 +0200
Subject: [PATCH 12/26] fix(mcp): preserve deletion snapshot cursors

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/foundation/compat_fs.c | 18 +++++++++++-------
 src/foundation/compat_fs.h | 10 +++++++++-
 src/mcp/mcp.c              | 15 +++++++++------
 tests/test_mcp.c           | 28 ++++++++++++++++++++++++++++
 4 files changed, 57 insertions(+), 14 deletions(-)

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/mcp/mcp.c b/src/mcp/mcp.c
index b53d4b30b..28afdb25d 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -13545,12 +13545,15 @@ static bool detect_snapshot_add_changed_file(cbm_mcp_server_t *srv, cbm_sha256_c
     memcpy(absolute + root_len + 1U, relative_path, relative_len + 1U);
 
     cbm_path_info_t info = {0};
-    if (cbm_path_info_utf8(absolute, &info) != 0) {
-        /* A missing path can be a legitimate deletion, but the portable
-         * metadata API cannot distinguish it from permission and transient
-         * inspection failures on every supported platform. Hash the observed
-         * state for diagnostics, but do not issue a cursor from incomplete
-         * evidence. Offset paging remains available. */
+    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;
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 5007e0226..00721c1d0 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -11387,7 +11387,35 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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);
     free(changed_cursor);
 
     cbm_mcp_server_free(srv);

From c7956bd2b8e3af5c02199d10146da85b0339b830 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 12:44:08 +0200
Subject: [PATCH 13/26] fix(mcp): preserve malformed raw source bytes

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/mcp.c          | 72 ++++++++++++++++++++++++++++++++++++------
 src/mcp/mcp_internal.h |  6 ++++
 tests/test_mcp.c       | 68 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 136 insertions(+), 10 deletions(-)

diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 28afdb25d..806fa533b 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -11905,10 +11905,55 @@ 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;
+        }
+        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;
+        }
+        break;
+    }
+    return start;
+}
+
+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. Both boundaries are
- * adjusted to UTF-8 code-point boundaries and the adjusted start is reported. */
+ * 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) {
@@ -11929,23 +11974,17 @@ static void search_raw_preview(grep_match_t *match, const char *content,
             }
         }
     }
-    while (start < total && search_utf8_continuation_byte((unsigned char)content[start])) {
-        start++;
-    }
+    start = search_utf8_page_start(content, total, start);
 
     size_t remaining = total - start;
     size_t returned = remaining < preview_capacity ? remaining : preview_capacity;
     size_t end = start + returned;
     if (end < total) {
-        while (end > start && end < total &&
-               search_utf8_continuation_byte((unsigned char)content[end])) {
-            end--;
-        }
+        end = search_utf8_page_end(content, total, end);
     }
     returned = end - start;
     memcpy(match->content, content + start, returned);
     match->content[returned] = '\0';
-    sanitize_utf8_inplace(match->content);
     match->content_start_byte = start;
     match->content_returned_bytes = returned;
     match->content_total_bytes = total;
@@ -11955,6 +11994,19 @@ static void search_raw_preview(grep_match_t *match, const char *content,
     match->content_truncated = start > 0 || end < total;
 }
 
+#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, 1, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0,
+                                 "", false, false, 0, false, json_format);
+}
+#endif
+
 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,
                                           const char *pattern, bool use_regex,
diff --git a/src/mcp/mcp_internal.h b/src/mcp/mcp_internal.h
index 70660f5f1..64c0e4170 100644
--- a/src/mcp/mcp_internal.h
+++ b/src/mcp/mcp_internal.h
@@ -64,6 +64,12 @@ void cbm_mcp_server_set_snapshot_read_test_hook(cbm_mcp_server_t *srv,
 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);
 #endif
 
 #endif
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 00721c1d0..c879f85e1 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -7845,6 +7845,73 @@ TEST(search_code_raw_preview_centers_late_match_and_pages_content_bytes) {
     PASS();
 }
 
+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 *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);
+
+    /* 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_match_locations_are_explicitly_bounded_and_expandable) {
     char tmp[256];
     snprintf(tmp, sizeof(tmp), "/tmp/cbm_srch_match_locations_XXXXXX");
@@ -15464,6 +15531,7 @@ SUITE(mcp) {
     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

From 52d26695b166f82f51aac6542119cff66e3122b3 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 13:00:50 +0200
Subject: [PATCH 14/26] perf(output): score prefix directories efficiently

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/compact_out.c | 113 ++++++++++++++++++++++++++++++++----------
 1 file changed, 88 insertions(+), 25 deletions(-)

diff --git a/src/mcp/compact_out.c b/src/mcp/compact_out.c
index 81df04fc9..0f22621c2 100644
--- a/src/mcp/compact_out.c
+++ b/src/mcp/compact_out.c
@@ -529,17 +529,48 @@ static size_t tree_semantic_prefix_boundary(const char *text, size_t shared) {
     return boundary;
 }
 
-static bool tree_prefix_matches(const char *value, const tree_prefix_candidate_t *candidate) {
-    return value && !output_text_requires_encoding(value, strlen(value)) && !needs_quotes(value) &&
-           strlen(value) >= candidate->len && memcmp(value, candidate->text, candidate->len) == 0;
+/* 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) || !tree_prefix_matches(value, &candidates[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) {
@@ -651,22 +682,37 @@ static void tree_table_rows_impl(cbm_sb_t *sb, const char *key, int nrows, const
         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++) {
-        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) &&
-                tree_prefix_matches(cells[cell], &candidates[i])) {
-                candidates[i].uses++;
-            }
-        }
+        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;
@@ -681,19 +727,21 @@ static void tree_table_rows_impl(cbm_sb_t *sb, const char *key, int nrows, const
         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++) {
-        /* Recompute the exclusive longest-prefix assignment without another
-         * allocation; shorter overlapping candidates may become unused. */
-        size_t exclusive_uses = 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) &&
-                tree_prefix_choice(cells[cell], candidates, selected_count, false) == i) {
-                exclusive_uses++;
-            }
-        }
-        candidates[i].active = exclusive_uses >= TREE_PREFIX_MIN_USES;
+        candidates[i].active = exclusive_uses[i] >= TREE_PREFIX_MIN_USES;
         if (candidates[i].active) {
             candidates[i].id = active_count++;
         }
@@ -705,12 +753,28 @@ static void tree_table_rows_impl(cbm_sb_t *sb, const char *key, int nrows, const
         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);
@@ -751,9 +815,7 @@ static void tree_table_rows_impl(cbm_sb_t *sb, const char *key, int nrows, const
             }
             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 = tree_column_is_prefixable(string_cols, prefix_cols, col)
-                             ? tree_prefix_choice(value, candidates, selected_count, true)
-                             : -1;
+            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);
@@ -789,6 +851,7 @@ static void tree_table_rows_impl(cbm_sb_t *sb, const char *key, int nrows, const
     free(compact_text);
     free(refs_key);
     free(rule_key);
+    free(active_choices);
     tree_prefix_candidates_free(candidates, candidate_count);
     free(candidates);
 }

From f4fb6e31fdf399816e625068dac190c05671f872 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 13:26:22 +0200
Subject: [PATCH 15/26] fix(output): require token-shaped directory savings

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/compact_out.c | 51 +++++++++++++++++++++++++++++++++++++++++--
 tests/test_mcp.c      | 34 +++++++++++++++++++++++++++--
 2 files changed, 81 insertions(+), 4 deletions(-)

diff --git a/src/mcp/compact_out.c b/src/mcp/compact_out.c
index 0f22621c2..7a7e415a7 100644
--- a/src/mcp/compact_out.c
+++ b/src/mcp/compact_out.c
@@ -428,6 +428,7 @@ enum {
     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,
@@ -444,6 +445,45 @@ typedef struct {
     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];
 }
@@ -836,8 +876,15 @@ static void tree_table_rows_impl(cbm_sb_t *sb, const char *key, int nrows, const
         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;
-        use_compact =
-            saving >= TREE_PREFIX_MIN_SAVING && saving * 100 >= plain_len * TREE_PREFIX_MIN_PERCENT;
+        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);
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index c879f85e1..29a950bd2 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -899,8 +899,38 @@ TEST(tree_table_uses_prefix_dictionary_only_when_it_materially_wins) {
                                  roundtrip_string_cols, roundtrip_prefix_cols);
     out = cbm_sb_finish(&sb);
     ASSERT_NOT_NULL(out);
-    ASSERT_NOT_NULL(strstr(out, "\"123456789012.\""));
-    ASSERT_NOT_NULL(strstr(out, "  @0+member_00\n"));
+    /* 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();
 }

From e436f2eeb9a1f547d8581837f0a36dd5831f58b2 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 13:13:25 +0200
Subject: [PATCH 16/26] fix(mcp): make semantic search contracts explicit

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/mcp.c          | 119 +++++++++++++++++++++++++++++++-----
 src/mcp/mcp_internal.h |   6 ++
 tests/test_mcp.c       | 136 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 247 insertions(+), 14 deletions(-)

diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 806fa533b..7559cdbd6 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -474,7 +474,7 @@ static const tool_def_t TOOLS[] = {
 
     {"search_graph", "Search graph",
      "Regex rows keep qn/file/lines and in/out over CALLS/USAGE/CALL_REFERENCE/INHERITS/"
-     "IMPLEMENTS. Pages: offset/limit structural; semantic_offset/semantic_limit semantic.",
+     "IMPLEMENTS. Pages: offset/limit; semantic_offset/semantic_limit.",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},"
      "\"query\":{\"type\":\"string\"},"
      "\"label\":{\"type\":\"string\"},\"name_pattern\":{\"type\":\"string\"},\"qn_pattern\":{"
@@ -482,7 +482,7 @@ static const tool_def_t TOOLS[] = {
      "\"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\"}},"
+     "\"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,"
@@ -3679,6 +3679,16 @@ static bool run_semantic_query_core(const char *args, cbm_store_t *store, const
     return type_error;
 }
 
+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 present;
+}
+
 /* ── Tree output for search_graph ───────────────────────────────────
  * Default response encoding chooses the smaller complete direct/grouped tree
  * (compact_out.h). format:"json" keeps a stable grouped model;
@@ -3801,7 +3811,9 @@ static void sg_emit_paging_tree(cbm_sb_t *sb, int total, int offset, const sg_re
                                 int requested_fields, bool connected_requested,
                                 size_t max_output_bytes, bool continuation_supported,
                                 bool continuation_requires_positive_limit) {
-    bool has_more = continuation_supported && sg_page_has_more(total, offset, plan->returned);
+    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);
@@ -3814,11 +3826,13 @@ static void sg_emit_paging_tree(cbm_sb_t *sb, int total, int offset, const sg_re
                                  : "continuation_requires_higher_budget",
                              true);
     }
-    bool truncated = has_more || plan->budget_hit;
+    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" : "page_limit");
+                            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);
@@ -3842,7 +3856,9 @@ static void sg_emit_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int t
                                 bool connected_requested, size_t max_output_bytes,
                                 bool continuation_supported,
                                 bool continuation_requires_positive_limit) {
-    bool has_more = continuation_supported && sg_page_has_more(total, offset, plan->returned);
+    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);
@@ -3856,11 +3872,13 @@ static void sg_emit_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int t
                                     : "continuation_requires_higher_budget",
                                 true);
     }
-    bool truncated = has_more || plan->budget_hit;
+    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" : "page_limit");
+                               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);
@@ -3880,15 +3898,31 @@ static void sg_emit_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int t
     }
 }
 
-static bool sg_semantic_has_more(const sg_semantic_page_t *semantic, int returned) {
+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 ? "eq" : "gte");
+    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) {
@@ -3899,14 +3933,19 @@ static void sg_emit_semantic_paging_tree(cbm_sb_t *sb, const sg_semantic_page_t
                                                   : "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 ? "eq" : "gte");
+                           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) {
@@ -3918,7 +3957,44 @@ static void sg_emit_semantic_paging_json(yyjson_mut_doc *doc, yyjson_mut_val *ro
                                     : "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_ids_tree(cbm_sb_t *sb, const cbm_search_output_t *out,
                                          int returned) {
@@ -4223,6 +4299,8 @@ static char *sg_render_payload(bool json_format, const cbm_search_output_t *out,
     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;
@@ -4243,7 +4321,7 @@ static char *sg_render_payload(bool json_format, const cbm_search_output_t *out,
             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, true,
+                            connected_requested, max_output_bytes, continuation_supported,
                             semantic_only && semantic->limit == 0);
         return cbm_sb_finish(&sb);
     }
@@ -4267,7 +4345,7 @@ static char *sg_render_payload(bool json_format, const cbm_search_output_t *out,
         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, true,
+                        connected_requested, max_output_bytes, continuation_supported,
                         semantic_only && semantic->limit == 0);
     char *json = yy_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
@@ -4354,7 +4432,11 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     if (semantic_offset < 0) {
         semantic_offset = 0;
     } else if (semantic_offset > MCP_QUERY_MAX_VISIBLE_ROWS) {
-        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
@@ -4373,6 +4455,15 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
      * 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]) {
         char *q_file_pattern = cbm_mcp_get_string_arg(args, "file_pattern");
         char *bm25_json = bm25_search(store, project, query, q_file_pattern, limit, offset,
diff --git a/src/mcp/mcp_internal.h b/src/mcp/mcp_internal.h
index 64c0e4170..4b1438c2a 100644
--- a/src/mcp/mcp_internal.h
+++ b/src/mcp/mcp_internal.h
@@ -70,6 +70,12 @@ char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
  * 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/tests/test_mcp.c b/tests/test_mcp.c
index 29a950bd2..13292507d 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -3216,6 +3216,140 @@ TEST(tool_search_graph_bm25_reports_candidate_saturation) {
     PASS();
 }
 
+/* `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);
+
+    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();
+}
+
+/* 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);
+
+    /* 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();
+}
+
 enum { MCP_TEST_SEMANTIC_VECTOR_DIM = 768 };
 
 static int mcp_test_insert_semantic_vector(cbm_store_t *store, const char *table,
@@ -15490,6 +15624,8 @@ SUITE(mcp) {
     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);

From f9e6750d4d15a24ebd6b8a1065254eb90e330d40 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 13:01:26 +0200
Subject: [PATCH 17/26] fix(mcp): scan code search without hit loss

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/mcp.c     | 656 ++++++++++++++++++++++------------------------
 src/store/store.c |   3 +-
 tests/test_mcp.c  | 217 ++++++++++++---
 3 files changed, 498 insertions(+), 378 deletions(-)

diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 7559cdbd6..931515ced 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -90,6 +90,7 @@ enum {
 #include <unistd.h>
 #include <poll.h>
 #include <fcntl.h>
+#include <sys/wait.h>
 #define mcp_fdopen fdopen
 #define mcp_close close
 #endif
@@ -10898,7 +10899,8 @@ typedef struct {
     int out_degree;
     int score;
     int *match_lines;
-    int match_count;
+    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;
 
@@ -11002,20 +11004,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);
         }
@@ -11023,19 +11027,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);
         }
@@ -11047,27 +11054,53 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
             /* -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);
+            snprintf(
+                cmd, cmd_sz,
+                "xargs -0 sh -c 'pat=$1; shift; grep -Hn %s --include=\"%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, file_pattern, tmpfile, filelist);
         } else {
-            snprintf(cmd, cmd_sz, "xargs -0 grep -Hn %s -f '%s' < '%s' 2>/dev/null", flag, tmpfile,
-                     filelist);
+            snprintf(
+                cmd, cmd_sz,
+                "xargs -0 sh -c 'pat=$1; shift; 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 {
         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,
+                     "find '%s' -type f -name '%s' -print0 2>/dev/null | LC_ALL=C sort -z | "
+                     "xargs -0 sh -c 'pat=$1; shift; 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' 2>/dev/null",
+                     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,
+                     "find '%s' -type f -print0 2>/dev/null | LC_ALL=C sort -z | "
+                     "xargs -0 sh -c 'pat=$1; shift; 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' 2>/dev/null",
+                     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 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);
     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;
@@ -11091,7 +11124,9 @@ static yyjson_mut_val *build_dedup_files_array(yyjson_mut_doc *doc, search_resul
         }
     }
     for (int fi = 0; fi < raw_count; fi++) {
-        int raw_index = raw_start + 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[raw_index].file) == 0) {
@@ -11233,16 +11268,6 @@ static bool aggregate_search_dirs(search_result_t *sr, int sr_count,
     return true;
 }
 
-static int count_truncated_raw_content(const grep_match_t *raw, int raw_count) {
-    int count = 0;
-    for (int i = 0; i < raw_count; i++) {
-        if (raw[i].content_truncated) {
-            count++;
-        }
-    }
-    return count;
-}
-
 static bool raw_content_has_next(const grep_match_t *match) {
     return match->content_start_byte + match->content_returned_bytes < match->content_total_bytes;
 }
@@ -11257,7 +11282,7 @@ static bool raw_match_fully_returned(const grep_match_t *match) {
 }
 
 static int search_match_lines_shown(const search_result_t *result, int match_limit) {
-    return result->match_count < match_limit ? result->match_count : 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) {
@@ -11286,7 +11311,8 @@ static char *search_match_lines_text(const search_result_t *result, int match_li
  * 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 result_start,
+                                         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,
@@ -11383,7 +11409,7 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
             return NULL;
         }
         for (int ri = 0; ri < raw_output; ri++) {
-            int raw_index = raw_start + 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);
@@ -11485,9 +11511,8 @@ static char *assemble_search_output_toon(search_result_t *sr, int sr_count, grep
                                             : "raw_continuation_requires_higher_budget",
                              true);
     }
-    int truncated_raw_content = count_truncated_raw_content(raw, raw_count);
-    if (truncated_raw_content > 0) {
-        cbm_tree_scalar_int(&sb, "raw_content_truncated", truncated_raw_content);
+    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);
@@ -11530,7 +11555,8 @@ 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 result_start, int result_limit,
+                                    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,
@@ -11615,7 +11641,7 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
         yyjson_mut_obj_add_val(doc, raw_obj, "cols", rcols);
         yyjson_mut_val *raw_arr = yyjson_mut_arr(doc);
         for (int ri = 0; ri < raw_output; ri++) {
-            int raw_index = raw_start + ri;
+            int raw_index = ri;
             yyjson_mut_val *row = yyjson_mut_arr(doc);
             yyjson_mut_arr_add_str(doc, row, raw[raw_index].file);
             yyjson_mut_arr_add_int(doc, row, raw[raw_index].line);
@@ -11695,9 +11721,8 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
                                                : "raw_continuation_requires_higher_budget",
                                 true);
     }
-    int truncated_raw_content = count_truncated_raw_content(raw, raw_count);
-    if (truncated_raw_content > 0) {
-        yyjson_mut_obj_add_int(doc, root_obj, "raw_content_truncated", truncated_raw_content);
+    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);
@@ -11769,8 +11794,9 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
  * 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 gm_count, int result_start, int result_limit,
-                                   int output_count, int raw_start, int raw_output,
+                                   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,
@@ -11778,16 +11804,17 @@ static char *render_search_payload(search_result_t *sr, int sr_count, grep_match
                                    bool budget_hit, bool json_format) {
     if (mode == 0 && !json_format) {
         return assemble_search_output_toon(
-            sr, sr_count, raw, raw_count, 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);
+            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, 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);
+        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;
     }
@@ -11827,9 +11854,10 @@ char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
         initialized++;
     }
     char *payload =
-        render_search_payload(results, row_count, NULL, 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);
+        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;
 }
@@ -11842,19 +11870,16 @@ static char *search_budget_floor(int sr_count, int raw_count, int gm_count, int
                                  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);
-        static const char *const cols[] = {"qn",      "label",           "file", "lines",
-                                           "matches", "matches_omitted", "in",   "out"};
-        cbm_tree_table_header(&sb, "results", 0, cols, 8);
-        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", 0);
         cbm_tree_scalar_bool(&sb, "has_more", result_has_more);
@@ -11864,42 +11889,32 @@ static char *search_budget_floor(int sr_count, int raw_count, int gm_count, int
                                                    : "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) {
-            cbm_tree_scalar_bool(&sb,
-                                 raw_limit == 0 ? "raw_continuation_requires_positive_limit"
-                                                : "raw_continuation_requires_higher_budget",
-                                 true);
+        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) {
-            cbm_tree_scalar_bool(&sb,
-                                 directory_limit == 0
-                                     ? "directory_continuation_requires_positive_limit"
-                                     : "directory_continuation_requires_higher_budget",
-                                 true);
+        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");
-        cbm_tree_scalar_int(&sb, "max_output_tokens", max_output_tokens);
-        cbm_tree_scalar_str(&sb, "continuation",
-                            "raise max_output_tokens; no partial row 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_int(doc, root, "total_grep_matches", gm_count);
     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_str(doc, root, "total_relation", scan_saturated ? "gte" : "eq");
     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);
@@ -11909,32 +11924,24 @@ static char *search_budget_floor(int sr_count, int raw_count, int gm_count, int
                                                   : "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) {
-        yyjson_mut_obj_add_bool(doc, root,
-                                raw_limit == 0 ? "raw_continuation_requires_positive_limit"
-                                               : "raw_continuation_requires_higher_budget",
-                                true);
+    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) {
-        yyjson_mut_obj_add_bool(doc, root,
-                                directory_limit == 0
-                                    ? "directory_continuation_requires_positive_limit"
-                                    : "directory_continuation_requires_higher_budget",
-                                true);
+    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");
-    yyjson_mut_obj_add_int(doc, root, "max_output_tokens", max_output_tokens);
-    yyjson_mut_obj_add_str(doc, root, "continuation",
-                           "raise max_output_tokens; no partial row was emitted");
     char *json = yy_doc_to_str(doc);
     yyjson_mut_doc_free(doc);
     return json;
@@ -11954,16 +11961,6 @@ static const char *strip_root_prefix(const char *path, const char *root, size_t
     return p;
 }
 
-static int grep_match_cmp(const void *left, const void *right) {
-    const grep_match_t *a = left;
-    const grep_match_t *b = right;
-    int file_order = strcmp(a->file, b->file);
-    if (file_order != 0) {
-        return file_order;
-    }
-    return (a->line > b->line) - (a->line < b->line);
-}
-
 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) {
@@ -12093,133 +12090,12 @@ char *cbm_mcp_render_raw_preview_for_testing(const char *content, bool content_o
     }
     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, 1, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0,
-                                 "", false, false, 0, false, json_format);
+    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
 
-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,
-                                          const char *pattern, bool use_regex,
-                                          bool raw_content_offset_set, size_t raw_content_offset,
-                                          int grep_limit, int *out_count, bool *out_saturated,
-                                          bool *out_oom) {
-    int gm_cap = CBM_SZ_64;
-    int gm_count = 0;
-    grep_match_t *gm = calloc((size_t)gm_cap, sizeof(*gm));
-    char *line = NULL;
-    size_t line_capacity = 0;
-    cbm_regex_t content_regex;
-    bool content_regex_ready = false;
-
-    if (out_saturated) {
-        *out_saturated = false;
-    }
-    if (out_oom) {
-        *out_oom = gm == NULL;
-    }
-    if (!gm) {
-        *out_count = 0;
-        return NULL;
-    }
-    content_regex_ready = use_regex && pattern &&
-                          cbm_regcomp(&content_regex, pattern, CBM_REG_EXTENDED) == CBM_REG_OK;
-    for (;;) {
-        ssize_t line_length = cbm_getline(&line, &line_capacity, fp);
-        if (line_length < 0) {
-            if (!feof(fp) && out_oom) {
-                *out_oom = true;
-            }
-            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;
-        }
-
-        /* 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) {
-            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 *path = line;
-        const char *file = strip_root_prefix(path, root_path, root_len);
-
-        if (has_path_filter && cbm_regexec(path_regex, file, 0, NULL, 0) != CBM_REG_OK) {
-            continue;
-        }
-
-        if (gm_count >= grep_limit) {
-            if (out_saturated) {
-                *out_saturated = true;
-            }
-            break;
-        }
-
-        if (gm_count >= gm_cap) {
-            int next_capacity = gm_cap * PAIR_LEN;
-            grep_match_t *grown = realloc(gm, (size_t)next_capacity * sizeof(*gm));
-            if (!grown) {
-                if (out_oom) {
-                    *out_oom = true;
-                }
-                break;
-            }
-            memset(grown + gm_cap, 0, (size_t)(next_capacity - gm_cap) * sizeof(*grown));
-            gm = grown;
-            gm_cap = next_capacity;
-        }
-        gm[gm_count].file = heap_strdup(file);
-        if (!gm[gm_count].file) {
-            if (out_oom) {
-                *out_oom = true;
-            }
-            break;
-        }
-        gm[gm_count].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(&gm[gm_count], content, raw_content_offset_set, raw_content_offset,
-                           match_known, match_start, match_end);
-        gm_count++;
-    }
-
-    free(line);
-    if (content_regex_ready) {
-        cbm_regfree(&content_regex);
-    }
-    if (out_oom && *out_oom) {
-        free_grep_matches(gm, gm_count);
-        *out_count = 0;
-        return NULL;
-    }
-    *out_count = gm_count;
-    return gm;
-}
-
 /* 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) {
     int best = CBM_NOT_FOUND;
@@ -12227,7 +12103,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;
             }
@@ -12255,8 +12138,19 @@ static bool set_search_result_identity(search_result_t *result, const cbm_node_t
 }
 
 static bool append_search_match_line(search_result_t *result, int line) {
-    if (result->match_count >= result->match_capacity) {
+    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;
@@ -12268,7 +12162,7 @@ static bool append_search_match_line(search_result_t *result, int line) {
         result->match_lines = grown;
         result->match_capacity = next_capacity;
     }
-    result->match_lines[result->match_count++] = line;
+    result->match_lines[result->match_stored_count++] = line;
     return true;
 }
 
@@ -12308,13 +12202,33 @@ static bool add_to_search_results(search_result_t **sr, int *sr_count, int *sr_c
 /* Match a single grep hit to the tightest containing node, then add to sr or raw. */
 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) {
         return add_to_search_results(sr, sr_count, sr_cap, &file_nodes[best], hit->line);
     } else {
-        if (*raw_count >= *raw_cap) {
-            int next_capacity = (*raw_cap == 0) ? CBM_SZ_32 : *raw_cap * PAIR_LEN;
+        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_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;
@@ -12322,9 +12236,9 @@ static bool classify_grep_hit(grep_match_t *hit, cbm_node_t *file_nodes, int fil
             *raw = grown;
             *raw_cap = next_capacity;
         }
-        (*raw)[*raw_count] = *hit;
+        (*raw)[*raw_stored_count] = *hit;
         hit->file = NULL;
-        (*raw_count)++;
+        (*raw_stored_count)++;
     }
     return true;
 }
@@ -12342,40 +12256,125 @@ 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 bool 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) {
-    if (gm_count > SKIP_ONE) {
-        qsort(gm, (size_t)gm_count, sizeof(*gm), grep_match_cmp);
-    }
-    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;
         }
-        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);
+        size_t len = (size_t)line_length;
+        while (len > 0 && (line[len - SKIP_ONE] == '\n' || line[len - SKIP_ONE] == '\r')) {
+            line[--len] = '\0';
         }
-        for (int mi = file_start; mi < i; mi++) {
-            if (!classify_grep_hit(&gm[mi], file_nodes, file_node_count, sr, sr_count, sr_cap, raw,
-                                   raw_count, raw_cap)) {
-                free_file_nodes(file_nodes, file_node_count);
-                return false;
+        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);
             }
         }
-        free_file_nodes(file_nodes, file_node_count);
+
+        grep_match_t hit = {0};
+        hit.file = heap_strdup(file);
+        if (!hit.file) {
+            ok = false;
+            break;
+        }
+        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(hit.file);
     }
-    return true;
+
+    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
@@ -12852,12 +12851,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
@@ -12873,20 +12866,27 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     (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;
     bool scan_saturated = false;
-    bool grep_oom = false;
-    grep_match_t *gm = NULL;
+    bool scan_ok = sr != NULL;
     if (scoped && scoped_written == 0) {
         /* The path_filter 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 = calloc(1U, sizeof(*gm)); /* empty set; freed below */
-        grep_oom = gm == NULL;
         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);
@@ -12894,6 +12894,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);
@@ -12901,48 +12902,22 @@ 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,
-                                  pattern, use_regex, raw_content_offset_set,
-                                  (size_t)raw_content_offset_arg, grep_limit, &gm_count,
-                                  &scan_saturated, &grep_oom);
-        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);
     }
 
-    if (grep_oom) {
-        free_grep_matches(gm, gm_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);
-    }
-
-    /* ── 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((size_t)sr_cap, sizeof(*sr));
-
-    int raw_cap = CBM_SZ_32;
-    int raw_count = 0;
-    grep_match_t *raw = calloc((size_t)raw_cap, sizeof(*raw));
-
-    if (!sr || !raw ||
-        !classify_all_grep_hits(gm, gm_count, store, project, &sr, &sr_count, &sr_cap, &raw,
-                                &raw_count, &raw_cap)) {
-        free_grep_matches(gm, gm_count);
+    if (!scan_ok) {
+        search_scratch_close(&scratch);
         free_search_results(sr, sr_count);
-        free_grep_matches(raw, raw_count);
+        free_grep_matches(raw, raw_stored_count);
         free(root_path);
         free(pattern);
         free(project);
@@ -12950,9 +12925,11 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         if (has_path_filter) {
             cbm_regfree(&path_regex);
         }
-        return cbm_mcp_text_result("out of memory", true);
+        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));
@@ -12962,9 +12939,8 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
             free(ids);
             free(in_degs);
             free(out_degs);
-            free_grep_matches(gm, gm_count);
             free_search_results(sr, sr_count);
-            free_grep_matches(raw, raw_count);
+            free_grep_matches(raw, raw_stored_count);
             free(root_path);
             free(pattern);
             free(project);
@@ -13012,16 +12988,12 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         output_count = result_limit;
     }
     int raw_start = raw_offset < raw_count ? raw_offset : raw_count;
-    int raw_output = raw_count - raw_start;
-    if (raw_output > raw_limit) {
-        raw_output = raw_limit;
-    }
+    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_grep_matches(gm, gm_count);
         free_search_results(sr, sr_count);
-        free_grep_matches(raw, raw_count);
+        free_grep_matches(raw, raw_stored_count);
         free(root_path);
         free(pattern);
         free(project);
@@ -13040,18 +13012,18 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     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, 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);
+        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, 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);
+            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
@@ -13060,19 +13032,19 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         raw_output--;
         free(payload);
         payload = render_search_payload(
-            sr, sr_count, raw, raw_count, 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);
+            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, 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);
+            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
@@ -13085,10 +13057,11 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         while (low <= high) {
             int middle = low + (high - low) / 2;
             char *candidate = render_search_payload(
-                sr, sr_count, raw, raw_count, 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);
+                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;
@@ -13106,10 +13079,11 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         } else {
             source_max_lines = 0;
             payload = render_search_payload(
-                sr, sr_count, raw, raw_count, 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);
+                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);
         }
     }
 
@@ -13121,10 +13095,11 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
         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, 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);
+                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;
@@ -13143,9 +13118,8 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     }
     char *result = cbm_mcp_text_result(payload ? payload : "out of memory", payload == NULL);
     free(payload);
-    free_grep_matches(gm, gm_count);
     free_search_results(sr, sr_count);
-    free_grep_matches(raw, raw_count);
+    free_grep_matches(raw, raw_stored_count);
     free(root_path);
     free(pattern);
     free(project);
diff --git a/src/store/store.c b/src/store/store.c
index d2b4d19ad..26fab0485 100644
--- a/src/store/store.c
+++ b/src/store/store.c
@@ -3364,7 +3364,8 @@ int cbm_store_list_files(cbm_store_t *s, const char *project, char ***out, int *
     }
 
     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 file_path IS NOT NULL AND file_path != '' "
+                      "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;
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 13292507d..c903a3d86 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -7341,18 +7341,26 @@ TEST(search_code_preserves_valid_utf8_source) {
     PASS();
 }
 
-TEST(search_code_reports_scan_saturation) {
+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 src_path[512];
-    snprintf(src_path, sizeof(src_path), "%s/many.c", tmp);
-    FILE *fp = cbm_fopen(src_path, "wb");
+
+    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 = 0; i < 501; i++) {
-        fprintf(fp, "int saturationneedle_%d = %d;\n", i, i);
+    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);
 
     cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
     ASSERT_NOT_NULL(srv);
@@ -7360,32 +7368,120 @@ TEST(search_code_reports_scan_saturation) {
     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 node = {.project = project,
-                       .label = "Function",
-                       .name = "many",
-                       .qualified_name = "search-saturation.many",
-                       .file_path = "many.c",
-                       .start_line = 1,
-                       .end_line = 501};
-    ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+    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);
+    }
 
-    char *resp = cbm_mcp_server_handle(
-        srv, "{\"jsonrpc\":\"2.0\",\"id\":97,\"method\":\"tools/call\","
-             "\"params\":{\"name\":\"search_code\",\"arguments\":{"
-             "\"pattern\":\"saturationneedle\",\"project\":\"search-saturation\","
-             "\"format\":\"json\"}}}");
-    ASSERT_NOT_NULL(resp);
+    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);
-    ASSERT_NOT_NULL(inner);
-    ASSERT_NOT_NULL(strstr(inner, "\"total_grep_matches\":500"));
-    ASSERT_NOT_NULL(strstr(inner, "\"total_relation\":\"gte\""));
-    ASSERT_NOT_NULL(strstr(inner, "\"scan_saturated\":true"));
-    ASSERT_NOT_NULL(strstr(inner, "\"truncated\":true"));
+    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);
-    cbm_unlink(src_path);
-    cbm_rmdir(tmp);
+    ASSERT_EQ(th_rmtree(tmp), 0);
+    ASSERT_TRUE(last_raw_reachable);
+    PASS();
+}
+
+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);
+
+    /* 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);
+
+    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);
+    ASSERT_EQ(th_rmtree(tmp), 0);
     PASS();
 }
 
@@ -7473,18 +7569,24 @@ TEST(search_code_raw_and_directory_remainders_are_independently_pageable) {
     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 = "fixture.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 = "fixture.function_hit",
+         .qualified_name = function_qn,
          .file_path = "graph-b/function.c",
          .start_line = 1,
          .end_line = 1},
@@ -7553,6 +7655,45 @@ TEST(search_code_raw_and_directory_remainders_are_independently_pageable) {
         !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);
@@ -7564,6 +7705,8 @@ TEST(search_code_raw_and_directory_remainders_are_independently_pageable) {
 
     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();
 }
 
@@ -8084,7 +8227,7 @@ TEST(search_code_match_locations_are_explicitly_bounded_and_expandable) {
     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 <= 100; line++) {
+    for (int line = 1; line <= 601; line++) {
         fprintf(source, "MATCH_LOCATION_%03d\n", line);
     }
     fclose(source);
@@ -8101,7 +8244,7 @@ TEST(search_code_match_locations_are_explicitly_bounded_and_expandable) {
                        .qualified_name = "search_match_locations.many_matches",
                        .file_path = "many.c",
                        .start_line = 1,
-                       .end_line = 100};
+                       .end_line = 601};
     ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
 
     char *response = cbm_mcp_handle_tool(
@@ -8117,7 +8260,8 @@ TEST(search_code_match_locations_are_explicitly_bounded_and_expandable) {
     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)), 92);
+    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);
@@ -8129,7 +8273,7 @@ TEST(search_code_match_locations_are_explicitly_bounded_and_expandable) {
     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 92"));
+    ASSERT_NOT_NULL(strstr(inner, "1;2;3;4;5;6;7;8 593"));
     free(inner);
     free(response);
 
@@ -8143,8 +8287,8 @@ TEST(search_code_match_locations_are_explicitly_bounded_and_expandable) {
     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)), 100);
-    ASSERT_EQ((int)yyjson_get_int(yyjson_arr_get(row, 5)), 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);
@@ -15689,7 +15833,8 @@ SUITE(mcp) {
     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_reports_scan_saturation);
+    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_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);

From 72b7a460c49e34c29fda274d30915fd718d148f5 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 13:25:06 +0200
Subject: [PATCH 18/26] fix(mcp): propagate fallback discovery failures

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/mcp.c    |  54 ++++++++++++++++--------
 tests/test_mcp.c | 108 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 144 insertions(+), 18 deletions(-)

diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 931515ced..b078166bc 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -11056,33 +11056,51 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
              * written by write_scoped_filelist. */
             snprintf(
                 cmd, cmd_sz,
-                "xargs -0 sh -c 'pat=$1; shift; grep -Hn %s --include=\"%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",
+                "xargs -0 sh -c 'pat=$1; shift; if [ \"$#\" -eq 0 ]; then exit 0; fi; "
+                "grep -Hn %s --include=\"%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, file_pattern, tmpfile, filelist);
         } else {
             snprintf(
                 cmd, cmd_sz,
-                "xargs -0 sh -c 'pat=$1; shift; 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",
+                "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,
-                     "find '%s' -type f -name '%s' -print0 2>/dev/null | LC_ALL=C sort -z | "
-                     "xargs -0 sh -c 'pat=$1; shift; 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' 2>/dev/null",
-                     root_path, file_pattern, flag, tmpfile);
+            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,
-                     "find '%s' -type f -print0 2>/dev/null | LC_ALL=C sort -z | "
-                     "xargs -0 sh -c 'pat=$1; shift; 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' 2>/dev/null",
-                     root_path, flag, tmpfile);
+            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
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index c903a3d86..a70efe7df 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -7485,6 +7485,113 @@ TEST(search_code_fails_closed_when_complete_scan_is_impossible) {
     PASS();
 }
 
+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));
+
+    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);
+
+    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");
@@ -15835,6 +15942,7 @@ SUITE(mcp) {
     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_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);

From d3306d32d69683e7b3f1c25181abdee2a7828ecd Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 13:30:43 +0200
Subject: [PATCH 19/26] fix(output): align discovery defaults and help

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 README.md             |  4 +--
 src/cli/cli.c         | 40 +++++++++++++++++++++++-
 src/mcp/compact_out.h | 15 +++++----
 src/mcp/mcp.c         | 13 ++++----
 tests/test_cli.c      | 45 +++++++++++++++++++++++++--
 tests/test_mcp.c      | 71 ++++++++++++++++++++++++++++++++++++++++++-
 6 files changed, 167 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 88396fd74..3de5331c1 100644
--- a/README.md
+++ b/README.md
@@ -578,11 +578,11 @@ Commands that mutate graph data use shared OS-backed, per-project locks. This se
 
 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 that table is at least 15% and 64 bytes smaller. 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. These are deterministic model-neutral byte savings that normally reduce tokens; exact token counts still depend on the caller's tokenizer.
+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 without sacrificing POSIX byte-string identities. A value containing malformed UTF-8 is emitted reversibly as `@bytes:<lowercase hex of every original byte>`. A valid 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.
+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:
 
diff --git a/src/cli/cli.c b/src/cli/cli.c
index e6e7762cf..4a5594c1b 100644
--- a/src/cli/cli.c
+++ b/src/cli/cli.c
@@ -12292,6 +12292,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 +12334,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 +12345,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/mcp/compact_out.h b/src/mcp/compact_out.h
index fa86c24e9..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
@@ -70,8 +68,9 @@ void cbm_tree_table_rows_typed(cbm_sb_t *sb, const char *key, int nrows, const c
 
 /* 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 it saves at
- * least 15% and 64 bytes. */
+ * 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);
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index b078166bc..ff29f9a31 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -474,8 +474,8 @@ static const tool_def_t TOOLS[] = {
      "},\"required\":[\"repo_path\"]}"},
 
     {"search_graph", "Search graph",
-     "Regex rows keep qn/file/lines and in/out over CALLS/USAGE/CALL_REFERENCE/INHERITS/"
-     "IMPLEMENTS. Pages: offset/limit; semantic_offset/semantic_limit.",
+     "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\"},"
      "\"label\":{\"type\":\"string\"},\"name_pattern\":{\"type\":\"string\"},\"qn_pattern\":{"
@@ -493,9 +493,9 @@ static const tool_def_t TOOLS[] = {
      "\"offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
      "\"max_output_tokens\":{\"type\":\"integer\",\"default\":3200,\"minimum\":128,"
      "\"maximum\":1000000},"
-     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"]},"
+     "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"},"
      "\"fields\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},"
-     "\"detail\":{\"type\":\"string\",\"enum\":[\"ids\",\"default\"]}},"
+     "\"detail\":{\"type\":\"string\",\"enum\":[\"ids\",\"default\"],\"default\":\"default\"}},"
      "\"required\":[\"project\"]}"},
 
     {"query_graph", "Query graph",
@@ -678,7 +678,7 @@ static const tool_def_t TOOLS[] = {
     {"detect_changes", "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\"]},"
+     "\"string\",\"enum\":[\"files\",\"impact\"],\"default\":\"impact\"},"
      "\"direction\":{\"type\":\"string\",\"enum\":[\"inbound\",\"outbound\",\"both\"],\"default\":"
      "\"inbound\",\"description\":\"inbound=callers; outbound=dependencies; both=union.\"},"
      "\"depth\":{\"type\":\"integer\",\"default\":2},"
@@ -13795,7 +13795,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
diff --git a/tests/test_cli.c b/tests/test_cli.c
index dfeaf7849..b39fae356 100644
--- a/tests/test_cli.c
+++ b/tests/test_cli.c
@@ -12356,10 +12356,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();
 }
 
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index a70efe7df..8651e21d0 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -1170,7 +1170,9 @@ 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, "Regex rows keep qn/file/lines and in/out over CALLS"));
+    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"));
@@ -1180,6 +1182,65 @@ TEST(mcp_tools_list_latest_metadata) {
     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
@@ -12083,12 +12144,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);
@@ -15801,6 +15869,7 @@ 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);

From f29109d08d01648c653d7bee7b741e12c2549160 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 14:54:50 +0200
Subject: [PATCH 20/26] fix(store): bind pagination to published generations

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/pipeline/pipeline.c    |  10 ++
 src/store/store.c          | 262 ++++++++++++++++++++++++++++++++-----
 src/store/store.h          |  12 +-
 tests/test_pipeline.c      | 246 ++++++++++++++++++++++------------
 tests/test_store_pragmas.c |  30 +++++
 5 files changed, 437 insertions(+), 123 deletions(-)

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 26fab0485..2fb063555 100644
--- a/src/store/store.c
+++ b/src/store/store.c
@@ -1598,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];
@@ -1617,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;
 }
 
diff --git a/src/store/store.h b/src/store/store.h
index f63fd7ae1..ddddf2a88 100644
--- a/src/store/store.h
+++ b/src/store/store.h
@@ -353,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.
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);

From 794d6f7d57366dce0e0cf2fdd0c30f51d1f31398 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 14:55:06 +0200
Subject: [PATCH 21/26] fix(mcp): keep compact pagination lossless

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/compact_out.c | 186 ++++++-----
 src/mcp/mcp.c         | 737 ++++++++++++++++++++++++++++++------------
 tests/test_mcp.c      | 567 +++++++++++++++++++++++---------
 3 files changed, 1040 insertions(+), 450 deletions(-)

diff --git a/src/mcp/compact_out.c b/src/mcp/compact_out.c
index 7a7e415a7..2fbbb8314 100644
--- a/src/mcp/compact_out.c
+++ b/src/mcp/compact_out.c
@@ -76,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;
@@ -178,7 +178,7 @@ bool cbm_output_encode_text(const char *data, size_t len, char **encoded, size_t
 
     bool valid_utf8 = true;
     size_t offset = 0;
-    while (offset < len) {
+    while (valid_utf8 && offset < len) {
         size_t sequence = utf8_sequence_length((const unsigned char *)data + offset, len - offset);
         if (!sequence) {
             valid_utf8 = false;
@@ -219,41 +219,47 @@ bool cbm_output_encode_text(const char *data, size_t len, char **encoded, size_t
     return true;
 }
 
-static bool needs_quotes(const char *s) {
-    if (!s || !*s) {
+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 */
     }
-    size_t remaining = strlen(s);
-    for (const char *p = s; *p; p++, remaining--) {
-        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, remaining);
-            if (!len) {
+            size_t sequence = utf8_sequence_length((const unsigned char *)s + offset, len - offset);
+            if (!sequence) {
                 return true;
             }
-            p += len - 1;
-            remaining -= 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);
-    size_t remaining = s ? strlen(s) : 0;
-    for (const char *p = s ? s : ""; *p; p++, remaining--) {
+    size_t offset = 0;
+    while (s && offset < len) {
+        const char *p = s + offset;
         switch (*p) {
         case '"':
             cbm_sb_append_n(sb, "\\\"", 2);
@@ -277,11 +283,11 @@ 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, remaining);
-                if (len) {
-                    cbm_sb_append_n(sb, p, len);
-                    p += len - 1;
-                    remaining -= 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 {
                     /* Callers normalize first; retain a defensive printable
                      * escape if an internal caller ever violates that rule. */
@@ -293,52 +299,69 @@ static void append_quoted(cbm_sb_t *sb, const char *s) {
             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;
     }
     char *encoded = NULL;
     size_t encoded_len = 0;
-    if (!cbm_output_encode_text(s, strlen(s), &encoded, &encoded_len)) {
+    if (!cbm_output_encode_text(s, len, &encoded, &encoded_len)) {
         sb->oom = true;
         return;
     }
     const char *safe = encoded ? encoded : s;
-    if (needs_quotes(safe)) {
-        append_quoted(sb, safe);
+    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, encoded ? encoded_len : strlen(safe));
+        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(cbm_sb_t *sb, const char *s) {
+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, strlen(raw), &encoded, &encoded_len)) {
+    if (!cbm_output_encode_text(raw, len, &encoded, &encoded_len)) {
         sb->oom = true;
         return;
     }
     const char *safe = encoded ? encoded : raw;
-    if (!*safe || needs_quotes(safe) || strpbrk(safe, ":()\\")) {
-        append_quoted(sb, safe);
+    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_n(sb, safe, encoded ? encoded_len : strlen(safe));
+        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) {
@@ -878,13 +901,12 @@ static void tree_table_rows_impl(cbm_sb_t *sb, const char *key, int nrows, const
         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;
+        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);
@@ -933,18 +955,18 @@ static void json_tree_indent(cbm_sb_t *sb, int depth) {
  * 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, int depth) {
-    size_t len = strlen(text);
+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");
 
-    const char *line = text;
+    size_t line_offset = 0;
     for (;;) {
-        const char *newline = strchr(line, '\n');
-        const char *end = newline ? newline : line + strlen(line);
+        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;
@@ -968,8 +990,8 @@ static void json_tree_block_string(cbm_sb_t *sb, const char *text, int depth) {
         if (!newline) {
             break;
         }
-        line = newline + 1;
-        if (*line == '\0') {
+        line_offset = (size_t)(newline - text) + 1;
+        if (line_offset == len) {
             break;
         }
     }
@@ -977,7 +999,7 @@ static void json_tree_block_string(cbm_sb_t *sb, const char *text, int depth) {
 
 static void json_tree_scalar(cbm_sb_t *sb, yyjson_val *value) {
     if (yyjson_is_str(value)) {
-        append_value(sb, yyjson_get_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)) {
@@ -1018,7 +1040,7 @@ static bool json_tree_array_is_object_table(yyjson_val *array, yyjson_val **firs
         yyjson_val *key;
         yyjson_val *unused;
         yyjson_obj_foreach(first, key_index, key_maximum, key, unused) {
-            if (!yyjson_obj_get(item, yyjson_get_str(key))) {
+            if (!yyjson_obj_getn(item, yyjson_get_str(key), yyjson_get_len(key))) {
                 return false;
             }
         }
@@ -1027,15 +1049,16 @@ static bool json_tree_array_is_object_table(yyjson_val *array, yyjson_val **firs
     return true;
 }
 
-static void json_tree_value(cbm_sb_t *sb, const char *key_name, yyjson_val *value, int depth);
+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, yyjson_val *array,
-                                   yyjson_val *first, 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(sb, key_name);
+    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);
@@ -1046,7 +1069,7 @@ static void json_tree_object_table(cbm_sb_t *sb, const char *key_name, yyjson_va
     yyjson_val *unused;
     yyjson_obj_foreach(first, key_index, key_maximum, column, unused) {
         cbm_sb_append_n(sb, " ", 1);
-        append_key(sb, yyjson_get_str(column));
+        append_key_n(sb, yyjson_get_str(column), yyjson_get_len(column));
     }
     cbm_sb_append_n(sb, ")\n", 2);
 
@@ -1060,7 +1083,7 @@ static void json_tree_object_table(cbm_sb_t *sb, const char *key_name, yyjson_va
             if (!first_cell) {
                 cbm_sb_append_n(sb, " ", 1);
             }
-            yyjson_val *cell = yyjson_obj_get(row, yyjson_get_str(column));
+            yyjson_val *cell = yyjson_obj_getn(row, yyjson_get_str(column), yyjson_get_len(column));
             json_tree_scalar(sb, cell);
             first_cell = false;
         }
@@ -1068,15 +1091,16 @@ static void json_tree_object_table(cbm_sb_t *sb, const char *key_name, yyjson_va
     }
 }
 
-static void json_tree_array(cbm_sb_t *sb, const char *key_name, yyjson_val *array, int depth) {
+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, array, first, depth);
+        json_tree_object_table(sb, key_name, key_len, array, first, depth);
         return;
     }
 
     json_tree_indent(sb, depth);
-    append_key(sb, key_name);
+    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);
@@ -1092,10 +1116,11 @@ static void json_tree_array(cbm_sb_t *sb, const char *key_name, yyjson_val *arra
             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), field_value, depth + 2);
+                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, "-", item, depth + 1);
+            json_tree_value(sb, "-", 1, item, depth + 1);
         } else {
             json_tree_indent(sb, depth + 1);
             cbm_sb_append(sb, "- ");
@@ -1105,10 +1130,11 @@ static void json_tree_array(cbm_sb_t *sb, const char *key_name, yyjson_val *arra
     }
 }
 
-static void json_tree_value(cbm_sb_t *sb, const char *key_name, yyjson_val *value, int depth) {
+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(sb, key_name);
+        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");
@@ -1118,26 +1144,28 @@ static void json_tree_value(cbm_sb_t *sb, const char *key_name, yyjson_val *valu
     }
     if (yyjson_is_obj(value)) {
         json_tree_indent(sb, depth);
-        append_key(sb, key_name);
+        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), child, depth + 1);
+            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, value, depth);
+        json_tree_array(sb, key_name, key_len, value, depth);
     } else if (yyjson_is_str(value) &&
-               (strchr(yyjson_get_str(value), '\n') || strchr(yyjson_get_str(value), '\r'))) {
+               !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(sb, key_name);
+        append_key_n(sb, key_name, key_len);
         cbm_sb_append(sb, ": ");
-        json_tree_block_string(sb, yyjson_get_str(value), depth);
+        json_tree_block_string(sb, yyjson_get_str(value), yyjson_get_len(value), depth);
     } else {
         json_tree_indent(sb, depth);
-        append_key(sb, key_name);
+        append_key_n(sb, key_name, key_len);
         cbm_sb_append(sb, ": ");
         json_tree_scalar(sb, value);
         cbm_sb_append_n(sb, "\n", 1);
@@ -1161,10 +1189,10 @@ char *cbm_json_to_tree(const char *json) {
         yyjson_val *key;
         yyjson_val *value;
         yyjson_obj_foreach(root, index, maximum, key, value) {
-            json_tree_value(&sb, yyjson_get_str(key), value, 0);
+            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", root, 0);
+        json_tree_array(&sb, "items", sizeof("items") - 1, root, 0);
     } else {
         cbm_sb_append(&sb, "value: ");
         json_tree_scalar(&sb, root);
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index ff29f9a31..69783f410 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -449,31 +449,29 @@ 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. full/moderate add semantic edges; fast omits them; "
-     "cross-repo-intelligence links indexed services. Results summarize coverage gaps.",
+    {"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\":"
      "\"Repository path\"},"
      "\"mode\":{\"type\":\"string\","
      "\"enum\":[\"full\",\"moderate\",\"fast\",\"cross-repo-intelligence\"],"
-     "\"default\":\"full\",\"description\":\"full: all files+semantic; moderate: "
-     "filtered+semantic; "
-     "fast: filtered without semantic; cross-repo-intelligence: link services.\"},"
+     "\"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\":\"Cross-repo targets; [\\\"*\\\"] means all.\"},"
      "\"name\":{\"type\":\"string\",\"description\":"
-     "\"Project-name override; Non-ASCII bytes are encoded and unsafe characters normalized.\"},"
+     "\"Name override; Non-ASCII bytes are encoded; unsafe characters normalized.\"},"
      "\"persistence\":{\"type\":\"boolean\",\"default\":false,\"description\":"
      "\"Write .codebase-memory/graph.db.zst.\"}"
      "},\"required\":[\"repo_path\"]}"},
 
-    {"search_graph", "Search graph",
+    {"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\"},"
@@ -498,86 +496,81 @@ static const tool_def_t TOOLS[] = {
      "\"detail\":{\"type\":\"string\",\"enum\":[\"ids\",\"default\"],\"default\":\"default\"}},"
      "\"required\":[\"project\"]}"},
 
-    {"query_graph", "Query graph",
-     "Run read-only Cypher for multi-hop patterns, aggregation, complexity, or cross-service "
-     "analysis. Defaults to 200 visible rows and reports exact or lower-bound totals plus "
-     "truncation. Use max_rows or Cypher SKIP/LIMIT to continue. graph=missed queries flagged "
-     "coverage files; absence there is not proof of completeness. Call get_graph_schema with "
-     "diagnostics=full to discover queryable property names.",
+    {"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\":"
-     "\"Visible row budget (default 200; max 99998). Zero preserves the legacy maximum "
-     "window. This never changes query evaluation.\",\"minimum\":0,\"default\":200},"
+     "\"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\":\"Skip materialized result rows for response paging; unlike Cypher "
-     "SKIP, this does not change query evaluation.\"},"
+     "\"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\":\"Approximate token sizing; deterministic ceiling is 4 UTF-8 bytes per "
-     "requested token. Rows are omitted only whole.\"},"
+     "\"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 encode repeated prefixes with a local @N+suffix directory; "
-     "json keeps direct strings.\"}},"
+     "\"description\":\"tree may use local @N+suffix prefix refs; json uses direct strings.\"}},"
      "\"required\":[\"query\",\"project\"]}"},
 
-    {"trace_path", "Trace path",
+    {"trace_path",
      "Trace callers/callees, data flow, or cross-service paths. Defaults exclude tests and "
-     "resolver evidence. Rows retain qn/hop; totals, relations, and continuations are explicit.",
+     "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,"
      "\"minimum\":1,\"maximum\":15},"
      "\"limit\":{\"type\":\"integer\",\"default\":100,\"minimum\":1,\"maximum\":5000,"
-     "\"description\":\"Visible rows per page; a gte relation flags the 5000-node engine "
-     "ceiling.\"},"
+     "\"description\":\"Rows/page; gte flags the 5000-node engine ceiling.\"},"
      "\"max_output_tokens\":{\"type\":\"integer\",\"default\":3200,\"minimum\":128,"
-     "\"maximum\":1000000,\"description\":\"Approximate token sizing; deterministic ceiling "
-     "is 4 UTF-8 bytes per requested token. Optional evidence/args yield before nearest graph "
-     "rows.\"},"
-     "\"cursor\":{\"type\":\"string\",\"description\":\"Pass tree next or JSON next_cursor back "
-     "with traversal args unchanged; max_output_tokens may be raised.\"},"
+     "\"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, argument-aware data_flow, or service-boundary edges.\"},"
+     "\"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 hop-risk labels.\"},\"include_tests\":{\"type\":\"boolean\","
      "\"default\":false},"
      "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\","
-     "\"description\":\"tree chooses the smaller complete direct/grouped shape; json preserves "
-     "a stable grouped table model.\"},"
+     "\"description\":\"tree chooses smaller complete direct/grouped output; json uses stable "
+     "grouped tables.\"},"
      "\"include_evidence\":{\"type\":\"boolean\",\"default\":false,"
      "\"description\":\"Add resolver class and confidence.\"}},"
      "\"required\":[\"function_name\",\"project\"]}"},
 
-    {"get_code_snippet", "Get code snippet",
-     "Read a symbol found by search_graph. auto returns bounded source, but outlines large "
-     "containers; full restores up to 500 lines; outline and source pages carry continuations. "
-     "coverage_note marks partial indexing.",
+    {"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\":"
-     "\"Qualified name from search_graph, or short name.\"},\"project\":{"
+     "\"search_graph qn, or short name.\"},\"project\":{"
      "\"type\":\"string\"},\"include_neighbors\":{"
      "\"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.\"},"
+     "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\":\"Approximate token sizing for auto/outline "
-     "(default 2500); deterministic ceiling is 4 UTF-8 bytes per requested token. Source is "
-     "reduced only at whole-line boundaries. Explicit full is uncapped unless this is set.\"},"
+     "\"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_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\"},"
@@ -586,25 +579,24 @@ static const tool_def_t TOOLS[] = {
      "\"offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0}},\"required\":["
      "\"project\"]}"},
 
-    {"get_architecture", "Get architecture",
-     "Get a compact architecture overview: counts, languages, packages, and entry points. "
-     "Request aspects for structure, dependencies, routes, hotspots, boundaries, layers, "
-     "clusters, cycles, or file tree; path scopes to a directory.",
+    {"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 "
-     "except file_tree; omit = languages/packages/entry_points. cycles is always opt-in.\"},"
+     "\"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-ranked text search. compact returns symbols; full adds bounded source; files paths.",
+    {"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\"},\"path_filter\":{\"type\":\"string\"},"
      "\"mode\":{\"type\":\"string\","
@@ -617,7 +609,7 @@ static const tool_def_t TOOLS[] = {
      "\"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 a match-centered preview.\"},"
+     "\"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},"
@@ -629,9 +621,7 @@ static const tool_def_t TOOLS[] = {
      "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
      "\"required\":[\"pattern\",\"project\"]}"},
 
-    {"list_projects", "List projects",
-     "List indexed projects with stable paging. Identity is "
-     "the lean default; request stats for graph sizes.",
+    {"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\"],"
@@ -639,29 +629,27 @@ static const tool_def_t TOOLS[] = {
      "\"limit\":{\"type\":\"integer\",\"default\":50,\"minimum\":1,\"maximum\":500},"
      "\"offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
      "\"metadata_only\":{\"type\":\"boolean\",\"default\":false,"
-     "\"description\":\"Compatibility mode: omit counts, size, and branch.\"}}}"},
-    {"delete_project", "Delete project", "Delete a project from the index",
+     "\"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 project readiness, counts, root, and coverage-gap counts. diagnostics=summary/full adds "
-     "sample/file rows; verbose adds Git-path diagnostics. Coverage is best-effort, not proof of "
-     "completeness; use check_index_coverage for cited paths.",
+    {"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.\"},"
+     "\"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 only, five samples, or up to "
+     "\"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",
-     "Best-effort coverage/freshness for exact paths or scopes. Paths and scopes page separately; "
-     "diagnostics=full adds raw detail. A clean result is not proof of completeness.",
+    {"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},"
@@ -675,8 +663,7 @@ static const tool_def_t TOOLS[] = {
      "\"required\":[\"project\"]"
      "}"},
 
-    {"detect_changes", "Detect changes",
-     "Map a Git diff to files and impact. Page with snapshot cursors.",
+    {"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\"],\"default\":\"impact\"},"
      "\"direction\":{\"type\":\"string\",\"enum\":[\"inbound\",\"outbound\",\"both\"],\"default\":"
@@ -692,27 +679,25 @@ static const tool_def_t TOOLS[] = {
      "\"module_offset\":{\"type\":\"integer\",\"default\":0,\"minimum\":0},"
      "\"module_cursor\":{\"type\":\"string\"},"
      "\"max_output_tokens\":{\"type\":\"integer\",\"default\":3200,\"minimum\":128,"
-     "\"maximum\":1000000,\"description\":\"Approximate token sizing; deterministic ceiling "
-     "is 4 UTF-8 bytes per requested token.\"},"
+     "\"maximum\":1000000,\"description\":\"Sizing hint; hard ceiling is 4 UTF-8 bytes/token.\"},"
      "\"base_branch\":{\"type\":"
      "\"string\",\"default\":\"main\"},\"since\":{\"type\":\"string\"},"
      "\"format\":{\"type\":\"string\",\"enum\":[\"tree\",\"json\"],\"default\":\"tree\"}},"
      "\"required\":"
      "[\"project\"]}"},
 
-    {"manage_adr", "Manage ADR", "Outline an ADR by default; get reads it; update replaces it",
+    {"manage_adr", "Outline an ADR by default; get reads it; update replaces it",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},\"mode\":{\"type\":"
      "\"string\",\"enum\":[\"outline\",\"get\",\"update\",\"sections\"],\"default\":\"outline\","
-     "\"description\":\"outline pages heading rows; get returns content; update replaces all; "
-     "sections is the legacy heading list.\"},\"content\":{\"type\":\"string\"},"
+     "\"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",
-     "Validate and count traces; graph edge creation is not implemented",
+    {"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\":"
@@ -774,7 +759,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);
@@ -4655,6 +4642,230 @@ static char *handle_search_graph(cbm_mcp_server_t *srv, const char *args) {
     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;
@@ -4742,7 +4953,8 @@ static const char *query_graph_truncation_reason(const cbm_cypher_result_t *resu
 
 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) {
+                                            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;
@@ -4769,6 +4981,10 @@ static char *query_graph_tree_response_text(const cbm_cypher_result_t *result, i
         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",
@@ -4786,7 +5002,8 @@ static char *query_graph_tree_response_text(const cbm_cypher_result_t *result, i
 }
 
 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) {
+                                            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;
@@ -4822,6 +5039,10 @@ static char *query_graph_json_response_text(const cbm_cypher_result_t *result, i
         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",
@@ -4901,10 +5122,12 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
     } else if (visible_limit < 0) {
         visible_limit = 1;
     }
-    int row_offset = cbm_mcp_get_int_arg(args, "offset", 0);
+    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
@@ -4914,10 +5137,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);
     }
@@ -4925,6 +5150,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;
@@ -4932,6 +5158,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;
@@ -4944,6 +5171,49 @@ 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};
     /* `max_rows` is a presentation budget, never an evaluation budget.
      * Executing at visible_limit+1 corrupts ORDER BY, DISTINCT, aggregation,
@@ -4955,10 +5225,32 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
         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. */
@@ -5012,8 +5304,8 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
         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);
+            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) {
@@ -5024,7 +5316,7 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
             }
         }
         json = query_graph_json_response_text(&result, row_offset, output_rows, available_rows,
-                                              exact_total);
+                                              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
@@ -5032,8 +5324,9 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
          * 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);
+            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;
@@ -5048,8 +5341,9 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
             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);
+                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) {
@@ -5073,7 +5367,8 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
             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);
+                    &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;
@@ -5083,8 +5378,9 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
                 free(candidate);
             }
             if (!json) {
-                json = query_graph_tree_response_text(&result, row_offset, output_rows,
-                                                      available_rows, exact_total, true);
+                json =
+                    query_graph_tree_response_text(&result, row_offset, output_rows, available_rows,
+                                                   exact_total, true, &cursor_context);
             }
         }
     }
@@ -5093,6 +5389,7 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
         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);
 
@@ -11054,21 +11351,19 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
             /* -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 sh -c 'pat=$1; shift; if [ \"$#\" -eq 0 ]; then exit 0; fi; "
-                "grep -Hn %s --include=\"%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, file_pattern, tmpfile, filelist);
+            snprintf(cmd, cmd_sz,
+                     "xargs -0 sh -c 'pat=$1; shift; if [ \"$#\" -eq 0 ]; then exit 0; fi; "
+                     "grep -Hn %s --include=\"%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, file_pattern, tmpfile, filelist);
         } else {
-            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);
+            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
@@ -11078,29 +11373,27 @@ static void build_grep_cmd(char *cmd, size_t cmd_sz, bool use_regex, bool scoped
          * 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,
-                "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);
+            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,
-                "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);
+            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
@@ -11330,13 +11623,12 @@ static char *search_match_lines_text(const search_result_t *result, int match_li
  * 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 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) {
+                                         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);
@@ -11572,15 +11864,12 @@ 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 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) {
+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);
@@ -11814,18 +12103,18 @@ static char *assemble_search_output(search_result_t *sr, int sr_count, grep_matc
 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) {
+                                   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);
+        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(
@@ -11873,9 +12162,8 @@ char *cbm_mcp_render_search_rows_for_testing(const char *const *qualified_names,
     }
     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);
+                              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;
 }
@@ -12015,8 +12303,7 @@ static bool search_utf8_continuation_byte(unsigned char byte) {
  * 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])) {
+    if (start >= total || !search_utf8_continuation_byte((unsigned char)content[start])) {
         return start;
     }
     size_t earliest = start > 3U ? start - 3U : 0U;
@@ -12108,9 +12395,8 @@ char *cbm_mcp_render_raw_preview_for_testing(const char *content, bool content_o
     }
     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);
+    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
 
@@ -12220,9 +12506,8 @@ static bool add_to_search_results(search_result_t **sr, int *sr_count, int *sr_c
 /* Match a single grep hit to the tightest containing node, then add to sr or raw. */
 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_offset, int raw_limit, int *raw_count,
-                              int *raw_stored_count, int *raw_cap,
-                              int *raw_content_truncated) {
+                              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) {
         return add_to_search_results(sr, sr_count, sr_cap, &file_nodes[best], hit->line);
@@ -12237,8 +12522,8 @@ static bool classify_grep_hit(grep_match_t *hit, cbm_node_t *file_nodes, int fil
             }
             (*raw_content_truncated)++;
         }
-        bool retain = raw_limit > 0 && raw_index >= raw_offset &&
-                      raw_index - raw_offset < raw_limit;
+        bool retain =
+            raw_limit > 0 && raw_index >= raw_offset && raw_index - raw_offset < raw_limit;
         if (!retain) {
             return true;
         }
@@ -12279,21 +12564,19 @@ static void free_file_nodes(cbm_node_t *nodes, int count) {
  * 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) {
+    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 content_regex_ready = use_regex && pattern &&
+                               cbm_regcomp(&content_regex, pattern, CBM_REG_EXTENDED) == CBM_REG_OK;
     bool ok = true;
 
     for (;;) {
@@ -13700,15 +13983,17 @@ static bool detect_snapshot_add_changed_file(cbm_mcp_server_t *srv, cbm_sha256_c
     detect_snapshot_add_field(hash, metadata);
     bool complete = true;
     if (info.is_regular) {
-        bool allow_open = true;
+        FILE *file = NULL;
 #ifdef CBM_ENABLE_TEST_SEAMS
-        if (srv && srv->snapshot_read_test_hook) {
-            allow_open = srv->snapshot_read_test_hook(srv->snapshot_read_test_context, absolute);
+        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
-        FILE *file = allow_open ? cbm_fopen(absolute, "rb") : NULL;
         if (file) {
             unsigned char buffer[64 * 1024];
             size_t count;
@@ -13736,9 +14021,9 @@ static bool detect_snapshot_add_changed_file(cbm_mcp_server_t *srv, cbm_sha256_c
 }
 
 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 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]) {
@@ -13848,6 +14133,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);
     }
 
+    /* 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(
+            "index_metadata_error: generation metadata is unreadable; reindex before detecting "
+            "changes",
+            true);
+    }
+
     /* 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. */
@@ -14171,9 +14472,6 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         qsort(files, (size_t)file_count, sizeof(*files), detect_changed_path_compare);
     }
 
-    /* resolve_store already called via get_project_root above */
-    cbm_store_t *store = srv->store;
-
     /* 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. */
@@ -14306,10 +14604,10 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
 
     /* The impact traversal: ONE multi-source BFS over all seeds. */
     cbm_traverse_result_t impact = {0};
-    bool truncated = false;
+    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, &truncated);
+                                  MCP_BFS_LIMIT_MAX, &impact, &engine_saturated);
     }
 
     detect_module_row_t *modules = NULL;
@@ -14325,14 +14623,12 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
      * 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);
-    char generation[96] = "unknown";
-    (void)cbm_store_generation(store, generation, sizeof(generation));
-    char detect_snapshot[33];
+    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);
 
-    const char *cursor_error = NULL;
     detect_cursor_t decoded_cursor = {0};
     bool cursor_supplied = (changed_cursor_arg && changed_cursor_arg[0]) ||
                            (impact_cursor_arg && impact_cursor_arg[0]) ||
@@ -14418,7 +14714,12 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
     bool output_budget_floor_exceeded = false;
     char *out_str = NULL;
 
-render_detect_output:
+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);
@@ -14434,6 +14735,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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);
         }
@@ -14441,12 +14745,11 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
          * 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);
-        bool changed_has_more = changed_start + changed_returned < file_count;
         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);
-            char cursor[80];
             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);
@@ -14476,7 +14779,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         free(changed_cells);
         cbm_tree_scalar_int(&sb, "seed_symbols", seed_count);
         if (want_symbols) {
-            detect_emit_impacted_tree(&sb, &impact, imp_start, imp_returned, truncated);
+            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];
@@ -14487,14 +14790,13 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             /* 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", truncated ? "gte" : "eq");
+            cbm_tree_scalar_str(&sb, "module_total_relation", engine_saturated ? "gte" : "eq");
             cbm_tree_scalar_int(&sb, "module_returned", module_returned);
-            bool module_has_more = module_start + module_returned < module_total;
             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);
-                char cursor[80];
                 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);
@@ -14529,13 +14831,13 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             }
             free(count_text);
             free(cells);
-            if (truncated) {
+            if (engine_saturated) {
                 cbm_tree_scalar_str(&sb, "hint",
                                     "impact hit the safety ceiling — narrow with a lower "
                                     "'depth' or a smaller diff");
             }
         }
-        if (truncated || output_budget_hit) {
+        if (response_truncated) {
             cbm_tree_scalar_bool(&sb, "truncated", true);
         }
         out_str = cbm_sb_finish(&sb);
@@ -14556,18 +14858,20 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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);
-        bool changed_has_more = changed_start + changed_returned < file_count;
         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);
-            char cursor[80];
             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);
@@ -14586,7 +14890,8 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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);
-        yyjson_mut_obj_add_str(doc, root_obj, "impacted_total_relation", truncated ? "gte" : "eq");
+        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 = imp_start; i < imp_start + imp_returned; i++) {
@@ -14603,7 +14908,6 @@ 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);
-        bool impacted_has_more = imp_start + imp_returned < impact.visited_count;
         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);
@@ -14621,9 +14925,8 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
         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",
-                                   truncated ? "gte" : "eq");
+                                   engine_saturated ? "gte" : "eq");
             yyjson_mut_obj_add_int(doc, root_obj, "module_returned", module_returned);
-            bool module_has_more = module_start + module_returned < module_total;
             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",
@@ -14655,7 +14958,7 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
             }
             yyjson_mut_obj_add_val(doc, root_obj, "impacted_modules", rollup);
         }
-        yyjson_mut_obj_add_bool(doc, root_obj, "truncated", truncated || output_budget_hit);
+        yyjson_mut_obj_add_bool(doc, root_obj, "truncated", response_truncated);
         out_str = yy_doc_to_str(doc);
         yyjson_mut_doc_free(doc);
     }
@@ -14686,6 +14989,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
                 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 "
@@ -14698,6 +15004,9 @@ static char *handle_detect_changes(cbm_mcp_server_t *srv, const char *args) {
                 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",
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 8651e21d0..a024cc665 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -614,6 +614,17 @@ TEST(tree_cell_reversibly_encodes_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}],"
@@ -650,9 +661,8 @@ TEST(json_to_tree_keeps_multiline_source_readable) {
 }
 
 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\"}]}";
+    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"
@@ -664,6 +674,23 @@ TEST(json_to_tree_quotes_dynamic_keys_without_line_injection) {
     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. */
@@ -919,14 +946,13 @@ TEST(tree_table_uses_prefix_dictionary_only_when_it_materially_wins) {
     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);
+        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);
+                                 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:"));
@@ -1156,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
@@ -1252,7 +1278,7 @@ TEST(mcp_metadata_byte_budget) {
 
     char *json = cbm_mcp_tools_list();
     ASSERT_NOT_NULL(json);
-    ASSERT_LT((int)strlen(json), 16 * 1024);
+    ASSERT_LT((int)strlen(json), 15 * 1024);
 
     yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
     ASSERT_NOT_NULL(doc);
@@ -3305,10 +3331,10 @@ TEST(tool_search_graph_rejects_bm25_and_semantic_query_together) {
                                     "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\"}");
+    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"));
@@ -3393,10 +3419,10 @@ TEST(tool_search_graph_semantic_ceiling_never_emits_unusable_continuation) {
     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\"}");
+    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"));
@@ -4129,6 +4155,219 @@ TEST(tool_query_graph_default_budget_is_truthful_and_expandable) {
     PASS();
 }
 
+/* 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);
+    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);
+    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);
+    PASS();
+}
+
 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);
@@ -7470,8 +7709,7 @@ TEST(search_code_scans_complete_stream_and_ranks_globally) {
         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 &&
+            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 &&
@@ -7532,10 +7770,10 @@ TEST(search_code_fails_closed_when_complete_scan_is_impossible) {
                           .end_line = 1};
     ASSERT_GT(cbm_store_upsert_node(store, &missing), 0);
 
-    char *response = cbm_mcp_handle_tool(
-        srv, "search_code",
-        "{\"pattern\":\"NEVER_SCANNED\",\"project\":\"search-incomplete\","
-        "\"format\":\"json\"}");
+    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"));
@@ -7566,10 +7804,9 @@ TEST(search_code_recursive_fallback_propagates_discovery_failures) {
     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"),
+    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);
@@ -7590,8 +7827,7 @@ TEST(search_code_recursive_fallback_propagates_discovery_failures) {
     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);
+    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);
 
@@ -7599,9 +7835,9 @@ TEST(search_code_recursive_fallback_propagates_discovery_failures) {
         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");
+    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 =
@@ -7612,9 +7848,9 @@ TEST(search_code_recursive_fallback_propagates_discovery_failures) {
         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");
+    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);
 
@@ -7779,33 +8015,31 @@ TEST(search_code_raw_and_directory_remainders_are_independently_pageable) {
         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_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_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;
+    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_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_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;
@@ -7823,14 +8057,13 @@ TEST(search_code_raw_and_directory_remainders_are_independently_pageable) {
         !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_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_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 &&
@@ -7847,11 +8080,11 @@ TEST(search_code_raw_and_directory_remainders_are_independently_pageable) {
     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_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 &&
@@ -8321,8 +8554,7 @@ TEST(search_code_raw_preview_centers_late_match_and_pages_content_bytes) {
 }
 
 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'};
+    const char malformed[] = {'H', 'E', 'A', 'D', (char)0x80, (char)0xff, 'T', 'A', 'I', 'L', '\0'};
 
     char *json = cbm_mcp_render_raw_preview_for_testing(malformed, false, 0, true);
     ASSERT_NOT_NULL(json);
@@ -8333,8 +8565,7 @@ TEST(search_code_raw_preview_reversibly_pages_malformed_utf8_bytes) {
     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_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);
@@ -11030,11 +11261,11 @@ TEST(tool_detect_changes_invalid_base_is_an_error) {
     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\"}");
+    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);
@@ -11056,7 +11287,9 @@ TEST(tool_detect_changes_preserves_utf8_git_path_and_impact_seed) {
     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";
+    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);
@@ -11107,17 +11340,15 @@ TEST(tool_detect_changes_preserves_utf8_git_path_and_impact_seed) {
                          .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"};
+    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 *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;
@@ -11128,9 +11359,8 @@ TEST(tool_detect_changes_preserves_utf8_git_path_and_impact_seed) {
     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;
+    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);
@@ -11158,11 +11388,11 @@ TEST(tool_detect_changes_finds_nested_untracked_file_and_impact_seed) {
     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",
+        "-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);
@@ -11207,10 +11437,8 @@ TEST(tool_detect_changes_finds_nested_untracked_file_and_impact_seed) {
                          .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"};
+    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(
@@ -11225,14 +11453,12 @@ TEST(tool_detect_changes_finds_nested_untracked_file_and_impact_seed) {
     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 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;
+    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);
@@ -11266,11 +11492,11 @@ TEST(tool_detect_changes_escapes_newline_path_in_tree_and_round_trips_json) {
     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",
+        "-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);
@@ -11293,28 +11519,25 @@ TEST(tool_detect_changes_escapes_newline_path_in_tree_and_round_trips_json) {
     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-newline-path-project\",\"base_branch\":\"HEAD\","
-        "\"scope\":\"files\",\"max_output_tokens\":10000}");
+    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;
+    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_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;
+    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);
@@ -11350,11 +11573,11 @@ TEST(tool_detect_changes_staged_rename_uses_exact_destination_record) {
     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",
+        "-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);
@@ -11381,19 +11604,18 @@ TEST(tool_detect_changes_staged_rename_uses_exact_destination_record) {
     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-rename-path-project\",\"base_branch\":\"HEAD\","
-        "\"scope\":\"files\",\"max_output_tokens\":10000,\"format\":\"json\"}");
+    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;
+    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);
@@ -11683,6 +11905,7 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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");
@@ -11711,6 +11934,7 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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"));
@@ -11739,6 +11963,7 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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);
@@ -11793,6 +12018,7 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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);
@@ -11859,6 +12085,7 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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);
@@ -11869,10 +12096,9 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
      * 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\"}");
+    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);
@@ -11915,10 +12141,9 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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\"}");
+    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);
@@ -11943,10 +12168,9 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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\"}");
+    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);
@@ -11959,6 +12183,32 @@ TEST(tool_detect_changes_pages_changed_files_and_honors_semantic_budget) {
     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);
@@ -12011,18 +12261,18 @@ TEST(tool_detect_changes_output_budget_sets_truncated_in_tree_and_json) {
     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_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_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;
@@ -15843,9 +16093,11 @@ SUITE(mcp) {
     RUN_TEST(jsonrpc_parse_notification);
     RUN_TEST(jsonrpc_parse_invalid);
     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);
@@ -15951,6 +16203,7 @@ SUITE(mcp) {
     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);

From e56e9f221f9a4f666f1e60d2b9d43760b7e3ece8 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 16:12:18 +0200
Subject: [PATCH 22/26] fix(search): scope scans to canonical source files

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/store/store.c        | 11 ++++++-
 src/store/store.h        |  4 +--
 tests/test_incremental.c | 10 ++++++
 tests/test_mcp.c         | 68 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 90 insertions(+), 3 deletions(-)

diff --git a/src/store/store.c b/src/store/store.c
index 2fb063555..760bda9d5 100644
--- a/src/store/store.c
+++ b/src/store/store.c
@@ -3553,8 +3553,17 @@ 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) {
diff --git a/src/store/store.h b/src/store/store.h
index ddddf2a88..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).
diff --git a/tests/test_incremental.c b/tests/test_incremental.c
index fed067f49..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();
 }
 
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index a024cc665..25ce1d173 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -7784,6 +7784,73 @@ TEST(search_code_fails_closed_when_complete_scan_is_impossible) {
     PASS();
 }
 
+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);
+
+    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"));
+
+    free(response);
+    cbm_mcp_server_free(srv);
+    cbm_unlink(source_path);
+    cbm_rmdir(source_dir);
+    cbm_rmdir(tmp);
+    PASS();
+}
+
 TEST(search_code_recursive_fallback_propagates_discovery_failures) {
 #ifdef _WIN32
     SKIP_PLATFORM("POSIX find/sort/xargs fallback contract");
@@ -16264,6 +16331,7 @@ SUITE(mcp) {
     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_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);

From f4fc43b238f2bf94eca05fb8933cde99c11468b7 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 17:14:54 +0200
Subject: [PATCH 23/26] test(cli): isolate activation runtime

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/cli/cli.c    |  4 ++++
 src/cli/cli.h    |  1 +
 tests/test_cli.c | 30 +++++++++++++++++++++++++++++-
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/src/cli/cli.c b/src/cli/cli.c
index 4a5594c1b..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:
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/tests/test_cli.c b/tests/test_cli.c
index b39fae356..d56ada449 100644
--- a/tests/test_cli.c
+++ b/tests/test_cli.c
@@ -54,6 +54,20 @@ 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, false));
     ASSERT_TRUE(cbm_cli_progress_enabled(false, false, true));
@@ -1129,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;
@@ -12732,6 +12746,16 @@ 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);
@@ -13101,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';
 }

From a2642b6cabc6fad167583b922d5556d673a8654e Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 17:32:52 +0200
Subject: [PATCH 24/26] test(watchdog): isolate daemon runtime

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 tests/test_parent_watchdog.sh | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

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=$!
 

From 589c342e16edb0cf205e2b7ed869038811d1fea1 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 17:50:57 +0200
Subject: [PATCH 25/26] test(watchdog): isolate worker runtime

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/main.c                          |  6 +++---
 tests/test_worker_error_response.sh | 13 +++++++++++--
 tests/test_worker_watchdog.sh       |  7 +++++++
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/src/main.c b/src/main.c
index 6c5273060..d68dff6b1 100644
--- a/src/main.c
+++ b/src/main.c
@@ -1562,7 +1562,7 @@ static cbm_daemon_bootstrap_status_t main_client_bootstrap_with_upgrade(
  * 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,
                                            bool quiet_requested) {
-    cbm_daemon_ipc_endpoint_t *endpoint = cbm_daemon_bootstrap_endpoint_new(NULL);
+    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 =
@@ -2487,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 =
@@ -2647,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 =
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" &

From ca33661684e63d0b8efbedf8cb6d0885a00e19e1 Mon Sep 17 00:00:00 2001
From: Martin Vogel <martin.vogel.tech@gmail.com>
Date: Thu, 13 Aug 2026 19:54:03 +0200
Subject: [PATCH 26/26] fix(search): make scoped file patterns portable

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
---
 src/mcp/mcp.c    | 50 ++++++++++++++++--------------
 tests/test_mcp.c | 81 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 108 insertions(+), 23 deletions(-)

diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 69783f410..ea1d731e9 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -87,6 +87,7 @@ enum {
 #define mcp_fdopen _fdopen
 #define mcp_close _close
 #else
+#include <fnmatch.h>
 #include <unistd.h>
 #include <poll.h>
 #include <fcntl.h>
@@ -11347,24 +11348,15 @@ 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 sh -c 'pat=$1; shift; if [ \"$#\" -eq 0 ]; then exit 0; fi; "
-                     "grep -Hn %s --include=\"%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, file_pattern, tmpfile, filelist);
-        } else {
-            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);
-        }
+        /* 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
@@ -12687,8 +12679,8 @@ static bool scan_and_classify_grep_matches(
  * 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) {
@@ -12725,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
@@ -13159,8 +13162,9 @@ 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. */
@@ -13182,7 +13186,7 @@ static char *handle_search_code(cbm_mcp_server_t *srv, const char *args) {
     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. */
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 25ce1d173..c3d47f1da 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -7851,6 +7851,86 @@ TEST(search_code_scoped_scan_uses_canonical_file_nodes) {
     PASS();
 }
 
+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));
+
+    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_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);
+
+    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");
+
+    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
+}
+
 TEST(search_code_recursive_fallback_propagates_discovery_failures) {
 #ifdef _WIN32
     SKIP_PLATFORM("POSIX find/sort/xargs fallback contract");
@@ -16332,6 +16412,7 @@ SUITE(mcp) {
     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);