@colbymchenry/codegraph-win32-arm64 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/lib/dist/bin/codegraph.js +145 -29
  2. package/lib/dist/bin/codegraph.js.map +1 -1
  3. package/lib/dist/context/formatter.d.ts +7 -1
  4. package/lib/dist/context/formatter.d.ts.map +1 -1
  5. package/lib/dist/context/formatter.js +12 -6
  6. package/lib/dist/context/formatter.js.map +1 -1
  7. package/lib/dist/context/index.d.ts +12 -0
  8. package/lib/dist/context/index.d.ts.map +1 -1
  9. package/lib/dist/context/index.js +60 -14
  10. package/lib/dist/context/index.js.map +1 -1
  11. package/lib/dist/db/index.d.ts +37 -0
  12. package/lib/dist/db/index.d.ts.map +1 -1
  13. package/lib/dist/db/index.js +101 -1
  14. package/lib/dist/db/index.js.map +1 -1
  15. package/lib/dist/db/migrations.d.ts +1 -1
  16. package/lib/dist/db/migrations.d.ts.map +1 -1
  17. package/lib/dist/db/migrations.js +25 -1
  18. package/lib/dist/db/migrations.js.map +1 -1
  19. package/lib/dist/db/queries.d.ts +160 -3
  20. package/lib/dist/db/queries.d.ts.map +1 -1
  21. package/lib/dist/db/queries.js +400 -33
  22. package/lib/dist/db/queries.js.map +1 -1
  23. package/lib/dist/db/schema.sql +16 -3
  24. package/lib/dist/directory.d.ts +29 -0
  25. package/lib/dist/directory.d.ts.map +1 -1
  26. package/lib/dist/directory.js +52 -0
  27. package/lib/dist/directory.js.map +1 -1
  28. package/lib/dist/extraction/extraction-version.d.ts +1 -1
  29. package/lib/dist/extraction/extraction-version.js +1 -1
  30. package/lib/dist/extraction/function-ref.d.ts.map +1 -1
  31. package/lib/dist/extraction/function-ref.js +6 -0
  32. package/lib/dist/extraction/function-ref.js.map +1 -1
  33. package/lib/dist/extraction/generated-detection.d.ts +48 -12
  34. package/lib/dist/extraction/generated-detection.d.ts.map +1 -1
  35. package/lib/dist/extraction/generated-detection.js +176 -11
  36. package/lib/dist/extraction/generated-detection.js.map +1 -1
  37. package/lib/dist/extraction/grammars.d.ts.map +1 -1
  38. package/lib/dist/extraction/grammars.js +38 -2
  39. package/lib/dist/extraction/grammars.js.map +1 -1
  40. package/lib/dist/extraction/index.d.ts +106 -0
  41. package/lib/dist/extraction/index.d.ts.map +1 -1
  42. package/lib/dist/extraction/index.js +284 -53
  43. package/lib/dist/extraction/index.js.map +1 -1
  44. package/lib/dist/extraction/languages/c-cpp.d.ts.map +1 -1
  45. package/lib/dist/extraction/languages/c-cpp.js +19 -4
  46. package/lib/dist/extraction/languages/c-cpp.js.map +1 -1
  47. package/lib/dist/extraction/languages/erlang.d.ts.map +1 -1
  48. package/lib/dist/extraction/languages/erlang.js +58 -22
  49. package/lib/dist/extraction/languages/erlang.js.map +1 -1
  50. package/lib/dist/extraction/languages/objc.d.ts.map +1 -1
  51. package/lib/dist/extraction/languages/objc.js +4 -0
  52. package/lib/dist/extraction/languages/objc.js.map +1 -1
  53. package/lib/dist/extraction/languages/rust.d.ts +20 -0
  54. package/lib/dist/extraction/languages/rust.d.ts.map +1 -1
  55. package/lib/dist/extraction/languages/rust.js +47 -20
  56. package/lib/dist/extraction/languages/rust.js.map +1 -1
  57. package/lib/dist/extraction/parse-pool.d.ts +7 -0
  58. package/lib/dist/extraction/parse-pool.d.ts.map +1 -1
  59. package/lib/dist/extraction/parse-pool.js +20 -1
  60. package/lib/dist/extraction/parse-pool.js.map +1 -1
  61. package/lib/dist/extraction/tree-sitter-types.d.ts +2 -0
  62. package/lib/dist/extraction/tree-sitter-types.d.ts.map +1 -1
  63. package/lib/dist/extraction/tree-sitter.d.ts +5 -1
  64. package/lib/dist/extraction/tree-sitter.d.ts.map +1 -1
  65. package/lib/dist/extraction/tree-sitter.js +106 -50
  66. package/lib/dist/extraction/tree-sitter.js.map +1 -1
  67. package/lib/dist/graph/queries.d.ts.map +1 -1
  68. package/lib/dist/graph/queries.js +2 -0
  69. package/lib/dist/graph/queries.js.map +1 -1
  70. package/lib/dist/graph/traversal.js +1 -1
  71. package/lib/dist/graph/traversal.js.map +1 -1
  72. package/lib/dist/index.d.ts +22 -0
  73. package/lib/dist/index.d.ts.map +1 -1
  74. package/lib/dist/index.js +117 -1
  75. package/lib/dist/index.js.map +1 -1
  76. package/lib/dist/installer/index.d.ts +4 -3
  77. package/lib/dist/installer/index.d.ts.map +1 -1
  78. package/lib/dist/installer/index.js +8 -6
  79. package/lib/dist/installer/index.js.map +1 -1
  80. package/lib/dist/installer/targets/claude.d.ts.map +1 -1
  81. package/lib/dist/installer/targets/claude.js +37 -5
  82. package/lib/dist/installer/targets/claude.js.map +1 -1
  83. package/lib/dist/installer/targets/codex.d.ts +22 -8
  84. package/lib/dist/installer/targets/codex.d.ts.map +1 -1
  85. package/lib/dist/installer/targets/codex.js +65 -48
  86. package/lib/dist/installer/targets/codex.js.map +1 -1
  87. package/lib/dist/installer/targets/copilot-cli.d.ts +32 -0
  88. package/lib/dist/installer/targets/copilot-cli.d.ts.map +1 -0
  89. package/lib/dist/installer/targets/copilot-cli.js +209 -0
  90. package/lib/dist/installer/targets/copilot-cli.js.map +1 -0
  91. package/lib/dist/installer/targets/copilot-jetbrains.d.ts +42 -0
  92. package/lib/dist/installer/targets/copilot-jetbrains.d.ts.map +1 -0
  93. package/lib/dist/installer/targets/copilot-jetbrains.js +238 -0
  94. package/lib/dist/installer/targets/copilot-jetbrains.js.map +1 -0
  95. package/lib/dist/installer/targets/copilot-vscode.d.ts +47 -0
  96. package/lib/dist/installer/targets/copilot-vscode.d.ts.map +1 -0
  97. package/lib/dist/installer/targets/copilot-vscode.js +219 -0
  98. package/lib/dist/installer/targets/copilot-vscode.js.map +1 -0
  99. package/lib/dist/installer/targets/registry.d.ts.map +1 -1
  100. package/lib/dist/installer/targets/registry.js +6 -0
  101. package/lib/dist/installer/targets/registry.js.map +1 -1
  102. package/lib/dist/installer/targets/toml.d.ts +6 -5
  103. package/lib/dist/installer/targets/toml.d.ts.map +1 -1
  104. package/lib/dist/installer/targets/toml.js +99 -20
  105. package/lib/dist/installer/targets/toml.js.map +1 -1
  106. package/lib/dist/installer/targets/types.d.ts +5 -5
  107. package/lib/dist/installer/targets/types.d.ts.map +1 -1
  108. package/lib/dist/mcp/daemon-manager.d.ts +1 -1
  109. package/lib/dist/mcp/daemon-manager.d.ts.map +1 -1
  110. package/lib/dist/mcp/daemon-manager.js +1 -1
  111. package/lib/dist/mcp/daemon-manager.js.map +1 -1
  112. package/lib/dist/mcp/daemon-paths.d.ts +6 -0
  113. package/lib/dist/mcp/daemon-paths.d.ts.map +1 -1
  114. package/lib/dist/mcp/daemon-paths.js +54 -0
  115. package/lib/dist/mcp/daemon-paths.js.map +1 -1
  116. package/lib/dist/mcp/daemon-registry.d.ts +10 -0
  117. package/lib/dist/mcp/daemon-registry.d.ts.map +1 -1
  118. package/lib/dist/mcp/daemon-registry.js +51 -3
  119. package/lib/dist/mcp/daemon-registry.js.map +1 -1
  120. package/lib/dist/mcp/daemon.d.ts +9 -6
  121. package/lib/dist/mcp/daemon.d.ts.map +1 -1
  122. package/lib/dist/mcp/daemon.js +10 -8
  123. package/lib/dist/mcp/daemon.js.map +1 -1
  124. package/lib/dist/mcp/engine.d.ts +3 -0
  125. package/lib/dist/mcp/engine.d.ts.map +1 -1
  126. package/lib/dist/mcp/engine.js +45 -3
  127. package/lib/dist/mcp/engine.js.map +1 -1
  128. package/lib/dist/mcp/explore-dedup.d.ts +137 -0
  129. package/lib/dist/mcp/explore-dedup.d.ts.map +1 -0
  130. package/lib/dist/mcp/explore-dedup.js +236 -0
  131. package/lib/dist/mcp/explore-dedup.js.map +1 -0
  132. package/lib/dist/mcp/explore-diagnostics.d.ts +289 -0
  133. package/lib/dist/mcp/explore-diagnostics.d.ts.map +1 -0
  134. package/lib/dist/mcp/explore-diagnostics.js +558 -0
  135. package/lib/dist/mcp/explore-diagnostics.js.map +1 -0
  136. package/lib/dist/mcp/explore-session-state.d.ts +217 -0
  137. package/lib/dist/mcp/explore-session-state.d.ts.map +1 -0
  138. package/lib/dist/mcp/explore-session-state.js +322 -0
  139. package/lib/dist/mcp/explore-session-state.js.map +1 -0
  140. package/lib/dist/mcp/index.d.ts +24 -0
  141. package/lib/dist/mcp/index.d.ts.map +1 -1
  142. package/lib/dist/mcp/index.js +67 -6
  143. package/lib/dist/mcp/index.js.map +1 -1
  144. package/lib/dist/mcp/liveness-watchdog.d.ts.map +1 -1
  145. package/lib/dist/mcp/liveness-watchdog.js +3 -1
  146. package/lib/dist/mcp/liveness-watchdog.js.map +1 -1
  147. package/lib/dist/mcp/proxy.d.ts.map +1 -1
  148. package/lib/dist/mcp/proxy.js +6 -1
  149. package/lib/dist/mcp/proxy.js.map +1 -1
  150. package/lib/dist/mcp/server-instructions.d.ts +2 -2
  151. package/lib/dist/mcp/server-instructions.d.ts.map +1 -1
  152. package/lib/dist/mcp/server-instructions.js +8 -3
  153. package/lib/dist/mcp/server-instructions.js.map +1 -1
  154. package/lib/dist/mcp/session.d.ts +16 -0
  155. package/lib/dist/mcp/session.d.ts.map +1 -1
  156. package/lib/dist/mcp/session.js +36 -13
  157. package/lib/dist/mcp/session.js.map +1 -1
  158. package/lib/dist/mcp/tools.d.ts +276 -10
  159. package/lib/dist/mcp/tools.d.ts.map +1 -1
  160. package/lib/dist/mcp/tools.js +2402 -241
  161. package/lib/dist/mcp/tools.js.map +1 -1
  162. package/lib/dist/project-config.d.ts +23 -0
  163. package/lib/dist/project-config.d.ts.map +1 -1
  164. package/lib/dist/project-config.js +39 -2
  165. package/lib/dist/project-config.js.map +1 -1
  166. package/lib/dist/resolution/c-fnptr-synthesizer.d.ts.map +1 -1
  167. package/lib/dist/resolution/c-fnptr-synthesizer.js +21 -19
  168. package/lib/dist/resolution/c-fnptr-synthesizer.js.map +1 -1
  169. package/lib/dist/resolution/callback-synthesizer.d.ts.map +1 -1
  170. package/lib/dist/resolution/callback-synthesizer.js +39 -11
  171. package/lib/dist/resolution/callback-synthesizer.js.map +1 -1
  172. package/lib/dist/resolution/frameworks/swift.d.ts.map +1 -1
  173. package/lib/dist/resolution/frameworks/swift.js +11 -1
  174. package/lib/dist/resolution/frameworks/swift.js.map +1 -1
  175. package/lib/dist/resolution/import-resolver.d.ts.map +1 -1
  176. package/lib/dist/resolution/import-resolver.js +18 -2
  177. package/lib/dist/resolution/import-resolver.js.map +1 -1
  178. package/lib/dist/resolution/index.d.ts.map +1 -1
  179. package/lib/dist/resolution/index.js +15 -4
  180. package/lib/dist/resolution/index.js.map +1 -1
  181. package/lib/dist/resolution/name-matcher.d.ts +30 -0
  182. package/lib/dist/resolution/name-matcher.d.ts.map +1 -1
  183. package/lib/dist/resolution/name-matcher.js +295 -5
  184. package/lib/dist/resolution/name-matcher.js.map +1 -1
  185. package/lib/dist/resolution/path-aliases.d.ts +6 -4
  186. package/lib/dist/resolution/path-aliases.d.ts.map +1 -1
  187. package/lib/dist/resolution/path-aliases.js +125 -17
  188. package/lib/dist/resolution/path-aliases.js.map +1 -1
  189. package/lib/dist/search/identifier-segments.d.ts +10 -0
  190. package/lib/dist/search/identifier-segments.d.ts.map +1 -1
  191. package/lib/dist/search/identifier-segments.js +29 -0
  192. package/lib/dist/search/identifier-segments.js.map +1 -1
  193. package/lib/dist/search/query-paths.d.ts +57 -0
  194. package/lib/dist/search/query-paths.d.ts.map +1 -0
  195. package/lib/dist/search/query-paths.js +298 -0
  196. package/lib/dist/search/query-paths.js.map +1 -0
  197. package/lib/dist/search/query-utils.d.ts +1 -1
  198. package/lib/dist/search/query-utils.d.ts.map +1 -1
  199. package/lib/dist/search/query-utils.js +13 -3
  200. package/lib/dist/search/query-utils.js.map +1 -1
  201. package/lib/dist/sync/watcher.d.ts +22 -0
  202. package/lib/dist/sync/watcher.d.ts.map +1 -1
  203. package/lib/dist/sync/watcher.js +51 -5
  204. package/lib/dist/sync/watcher.js.map +1 -1
  205. package/lib/dist/types.d.ts +20 -1
  206. package/lib/dist/types.d.ts.map +1 -1
  207. package/lib/dist/types.js +1 -0
  208. package/lib/dist/types.js.map +1 -1
  209. package/lib/kernel/codegraph-kernel.node +0 -0
  210. package/lib/node_modules/.package-lock.json +1 -1
  211. package/lib/package.json +1 -1
  212. package/package.json +1 -1
@@ -5,10 +5,12 @@
5
5
  * Defines the tools exposed by the CodeGraph MCP server.
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.ToolHandler = exports.tools = exports.PathRefusalError = exports.NotIndexedError = void 0;
8
+ exports.ToolHandler = exports.tools = exports.EXPLORE_ALLOCATION = exports.RELEVANCE_KIND_WEIGHT = exports.PathRefusalError = exports.NotIndexedError = void 0;
9
+ exports.__setLoadCodeGraphForTests = __setLoadCodeGraphForTests;
9
10
  exports.normalizeQuerySpelling = normalizeQuerySpelling;
10
11
  exports.getExploreBudget = getExploreBudget;
11
12
  exports.getExploreOutputBudget = getExploreOutputBudget;
13
+ exports.allocateExploreBudget = allocateExploreBudget;
12
14
  exports.formatStaleBanner = formatStaleBanner;
13
15
  exports.formatStaleFooter = formatStaleFooter;
14
16
  exports.formatDegradedBanner = formatDegradedBanner;
@@ -19,14 +21,27 @@ const directory_1 = require("../directory");
19
21
  // schemas), but it must NOT drag in sqlite/query layers before the daemon binds;
20
22
  // CodeGraph is pulled in only when a tool actually opens a project. require() is
21
23
  // sync + cached (CommonJS build).
22
- const loadCodeGraph = () => require('../index').default;
24
+ const loadCodeGraph = () => loadCodeGraphForTests ?? require('../index').default;
25
+ // Test seam (same pattern as the watcher's `__setFsWatchForTests`): vitest's
26
+ // module transform can't service the lazy `require('../index')` above, so
27
+ // in-process tests that exercise a genuine cross-project open (an explicit
28
+ // `projectPath` to a different project — issue #1474's repro shape) inject the
29
+ // already-imported class here. Never set outside tests.
30
+ let loadCodeGraphForTests = null;
31
+ function __setLoadCodeGraphForTests(cls) {
32
+ loadCodeGraphForTests = cls;
33
+ }
23
34
  const worktree_1 = require("../sync/worktree");
24
35
  const query_utils_1 = require("../search/query-utils");
36
+ const query_paths_1 = require("../search/query-paths");
25
37
  const fs_1 = require("fs");
38
+ const crypto_1 = require("crypto");
26
39
  const utils_1 = require("../utils");
27
- const generated_detection_1 = require("../extraction/generated-detection");
28
40
  const dynamic_boundaries_1 = require("./dynamic-boundaries");
29
41
  const update_check_1 = require("../upgrade/update-check");
42
+ const explore_diagnostics_1 = require("./explore-diagnostics");
43
+ const explore_session_state_1 = require("./explore-session-state");
44
+ const explore_dedup_1 = require("./explore-dedup");
30
45
  /**
31
46
  * An expected, recoverable "codegraph can't serve this" condition — most
32
47
  * importantly a project with no index. The dispatch catch converts these to
@@ -80,11 +95,16 @@ const RUST_PATH_PREFIXES = new Set(['crate', 'super', 'self']);
80
95
  * multi-thousand-character wall of source that bloats the agent's context.
81
96
  */
82
97
  const CONTAINER_NODE_KINDS = new Set([
83
- 'class', 'struct', 'interface', 'trait', 'protocol', 'enum', 'namespace', 'module',
98
+ 'class', 'struct', 'union', 'interface', 'trait', 'protocol', 'enum', 'namespace', 'module',
84
99
  ]);
85
- /** Last `::` / `.` / `/`-separated segment of a qualified symbol. */
100
+ /**
101
+ * Last `::` / `.` / `/`-separated segment of a qualified symbol. An Erlang
102
+ * arity tail (`mod::fn/3`, `fn/3`) is stripped first — the useful last segment
103
+ * is the function name, never the digits (#1610).
104
+ */
86
105
  function lastQualifierPart(symbol) {
87
- const parts = symbol.split(/::|[./]/).filter((p) => p.length > 0);
106
+ const noArity = symbol.replace(/\/\d{1,3}$/, '') || symbol;
107
+ const parts = noArity.split(/::|[./]/).filter((p) => p.length > 0);
88
108
  return parts[parts.length - 1] ?? symbol;
89
109
  }
90
110
  /**
@@ -158,7 +178,6 @@ function getExploreOutputBudget(fileCount) {
158
178
  includeAdditionalFiles: false,
159
179
  includeCompletenessSignal: false,
160
180
  includeBudgetNote: false,
161
- excludeLowValueFiles: true,
162
181
  };
163
182
  }
164
183
  if (fileCount < 500) {
@@ -174,7 +193,6 @@ function getExploreOutputBudget(fileCount) {
174
193
  includeAdditionalFiles: false,
175
194
  includeCompletenessSignal: false,
176
195
  includeBudgetNote: false,
177
- excludeLowValueFiles: true,
178
196
  };
179
197
  }
180
198
  if (fileCount < 5000) {
@@ -192,7 +210,6 @@ function getExploreOutputBudget(fileCount) {
192
210
  includeAdditionalFiles: true,
193
211
  includeCompletenessSignal: true,
194
212
  includeBudgetNote: true,
195
- excludeLowValueFiles: false,
196
213
  };
197
214
  }
198
215
  // Large + very-large repos: SAME ~24K inline ceiling (a bigger response just
@@ -211,7 +228,6 @@ function getExploreOutputBudget(fileCount) {
211
228
  includeAdditionalFiles: true,
212
229
  includeCompletenessSignal: true,
213
230
  includeBudgetNote: true,
214
- excludeLowValueFiles: false,
215
231
  };
216
232
  }
217
233
  return {
@@ -225,9 +241,404 @@ function getExploreOutputBudget(fileCount) {
225
241
  includeAdditionalFiles: true,
226
242
  includeCompletenessSignal: true,
227
243
  includeBudgetNote: true,
228
- excludeLowValueFiles: false,
229
244
  };
230
245
  }
246
+ // ── Explore relevance scoring (CG-10 / #1500) ──────────────────────────────
247
+ //
248
+ // A file earns its slice of the explore envelope from the symbols in it that the
249
+ // query matched. Before this weighting every match counted the same per tier, so
250
+ // a file that merely declares a local `const explore` scored what a file that
251
+ // DEFINES the explore pipeline scored — which is how three
252
+ // `scripts/agent-eval/*.mjs` harnesses took 63% of this repo's own "how does
253
+ // explore allocate its output budget across files" response on nothing but a
254
+ // local `explore` and a `BUDGET` constant. Four levers — the first three are
255
+ // multiplicative, so they compose without ordering surprises; the fourth decides
256
+ // admission from the result:
257
+ //
258
+ // 1. KIND — what a match on this NodeKind actually tells you (below).
259
+ // 2. ISOLATION — a weak-kind symbol nothing calls or references is a pure name
260
+ // collision; participation in the graph is the corroboration.
261
+ // 3. PENALTY — generated / test / i18n files are weaker answers to an
262
+ // architecture question at EVERY signal, not just as the
263
+ // tiebreak-at-equal-score they used to be.
264
+ // 4. FLOOR — admission scales with the best file's score, replacing an
265
+ // absolute bar that admitted noise wherever the top score was
266
+ // high.
267
+ /**
268
+ * How strongly a match on a symbol of this kind corroborates that its FILE is
269
+ * what the query is about.
270
+ *
271
+ * 1.0 a callable or a type — the unit an architecture question is about
272
+ * ~0.5 a member of a type, or the file node itself (a path match, not a
273
+ * symbol match)
274
+ * ~0.3 a variable / constant — as often a name collision as a definition
275
+ * 0.15 a parameter — essentially never the subject of a question
276
+ *
277
+ * Unlisted kinds fall back to `DEFAULT_RELEVANCE_KIND_WEIGHT`, so a NodeKind
278
+ * added later is neither free nor fatal.
279
+ */
280
+ exports.RELEVANCE_KIND_WEIGHT = {
281
+ // Callables and types: the answer lives in one of these.
282
+ function: 1, method: 1, class: 1, struct: 1, union: 1, interface: 1, trait: 1,
283
+ protocol: 1, component: 1, route: 1, enum: 1, type_alias: 1, constructor: 1,
284
+ // Containers: real structure, but a whole namespace/module matching a term is
285
+ // a coarser signal than a callable matching it.
286
+ namespace: 0.8, module: 0.8,
287
+ // Members of a type: real, weaker on their own.
288
+ property: 0.5, field: 0.5, enum_member: 0.35,
289
+ // The file node itself — the path matched, no symbol did.
290
+ file: 0.5,
291
+ // Incidental until the graph corroborates them (see ISOLATED_ below).
292
+ constant: 0.35, variable: 0.3, parameter: 0.15,
293
+ };
294
+ const DEFAULT_RELEVANCE_KIND_WEIGHT = 0.5;
295
+ /**
296
+ * Kinds whose evidentiary value depends on whether anything USES them. An
297
+ * exported `const DEFAULTS` that half the codebase references is a real
298
+ * definition; a `const explore` living inside one function of an eval script is
299
+ * a name collision. Only these kinds pay for the isolation probe.
300
+ */
301
+ const WEAK_RELEVANCE_KINDS = new Set([
302
+ 'constant', 'variable', 'parameter', 'field', 'property', 'enum_member',
303
+ ]);
304
+ /** Weight for a weak-kind symbol with no incoming/outgoing usage edge at all. */
305
+ const ISOLATED_WEAK_KIND_WEIGHT = 0.08;
306
+ /**
307
+ * Edges that mean "this symbol is used". `contains` is lexical nesting, not
308
+ * usage — counting it would make every file-scope constant look corroborated,
309
+ * which is exactly the case this guards against.
310
+ */
311
+ const RELEVANCE_USAGE_EDGES = new Set([
312
+ 'calls', 'references', 'extends', 'implements', 'overrides',
313
+ 'instantiates', 'returns', 'type_of', 'decorates',
314
+ ]);
315
+ /**
316
+ * Cap on what PERIPHERAL nodes (in the subgraph, but neither a query match nor
317
+ * adjacent to one) can contribute to a file's score. Uncapped, each such node
318
+ * added a flat +1, so a file grew more "relevant" simply by being bigger —
319
+ * `parse-session.mjs` reached score 22 off ONE incidental constant plus twelve
320
+ * unrelated symbols. Size is not evidence; cap its contribution.
321
+ */
322
+ const PERIPHERAL_SCORE_CAP = 5;
323
+ /**
324
+ * Rank penalties, applied to BOTH the relevance score and the graph mass.
325
+ *
326
+ * Generated source used to be a tiebreak at equal score only, so a generated
327
+ * file that outscored the hand-written one still won — the #1500 report exactly:
328
+ * the FKIT CRUD layer carries every query term AND more graph mass than the
329
+ * use-case that implements the business rule. A multiplier demotes it on the
330
+ * PRIMARY sort key instead, without ever hard-excluding it (ask about the
331
+ * generated API by name and the named-seed tier still puts it first). It is
332
+ * self-normalizing: in an all-generated repo everything scales together and
333
+ * relative ranking is untouched.
334
+ */
335
+ const GENERATED_RANK_PENALTY = 0.3;
336
+ /**
337
+ * Test/spec/icon/i18n files. These are normally hard-excluded outright, but that
338
+ * filter stands down when fewer than 2 non-low-value candidates remain (else
339
+ * tests would be the only signal for the area). This is the softened form for
340
+ * that case: down-weighted rather than removed.
341
+ */
342
+ const LOW_VALUE_RANK_PENALTY = 0.5;
343
+ /**
344
+ * Ambient declaration files — a hand-written `.d.ts` of global shims, vendored
345
+ * typings, module augmentation (CG-28). Declares nothing but types, and nothing
346
+ * in the index depends on it.
347
+ *
348
+ * Such a file cannot answer a FLOW question no matter how much its identifiers
349
+ * overlap the query: no bodies, no call edges, no behaviour, and nothing typed
350
+ * by it. Its ceiling of usefulness is a type signature, and one follow-up
351
+ * explore fetches that. But the identifiers it declares are exactly the generic
352
+ * ones a prose question uses (`Body`, `Message`, `ImageMetadata`,
353
+ * `ReadableStream`), so on term overlap it out-scores the implementation and
354
+ * takes the envelope — measured at rank #1 and 51% of delivered source, with
355
+ * the flow's own entry file getting none.
356
+ *
357
+ * Softer than {@link GENERATED_RANK_PENALTY} on purpose: "generated" is a claim
358
+ * about provenance the file itself makes, while this is an inference about what
359
+ * a file can be USEFUL for. A demoted declaration file that is still the best
360
+ * candidate should keep its place; the penalty only has to stop it beating real
361
+ * implementation. It does NOT stack with the generated penalty (see rankPenalty)
362
+ * — penalising twice for the same property is how a file gets cliffed out of
363
+ * answers where it is genuinely relevant.
364
+ */
365
+ const AMBIENT_DECLARATION_RANK_PENALTY = 0.5;
366
+ /**
367
+ * The type-level NodeKinds. Must stay in step with the kind list in
368
+ * `QueryBuilder.getAmbientDeclarationPathsAmong` — that query decides which
369
+ * files are ambient declarations, this set decides which symbols in them the
370
+ * agent can name to lift the penalty back off.
371
+ */
372
+ const DECLARATION_KINDS = new Set(['interface', 'type_alias', 'enum', 'enum_member', 'namespace']);
373
+ /**
374
+ * Score floor: `clamp(topScore * FRACTION, ABSOLUTE, MAX)`.
375
+ *
376
+ * An absolute floor alone (`>= 3`) admits noise on any repo where the top file
377
+ * scores 50+, so the bar is now a FRACTION of the best file's score and scales
378
+ * with how strong the best match is. On a diffuse survey question no file
379
+ * dominates, every candidate sits near the top score, and the whole spread gets
380
+ * through; on a precise question it cuts the long tail of incidental matches.
381
+ *
382
+ * ABSOLUTE is recalibrated for kind-weighted scores: the old `>= 3` assumed an
383
+ * unweighted tier sum where any query match was worth 10. A file whose sole
384
+ * match is an unused local constant now scores 0.8, so 3 had quietly become a
385
+ * much harsher admission bar than it was written to be — and the relative floor
386
+ * is what this change means to prune with anyway.
387
+ */
388
+ const SCORE_FLOOR_ABSOLUTE = 1;
389
+ const SCORE_FLOOR_FRACTION_OF_TOP = 0.2;
390
+ /**
391
+ * Ceiling on the relative floor, in units of one direct query match on a
392
+ * callable (the `entryNodeIds` tier, weight 1.0). A single full-strength match
393
+ * is never incidental, so no amount of concentration elsewhere may exclude it:
394
+ * one named-seed-heavy file (`+50` per seed) otherwise pushed the floor to 21
395
+ * and dropped `BridgeInterceptor`'s file, which the agent had named — a class,
396
+ * so it entered at the +10 tier rather than +50. The #1500 noise this change
397
+ * targets scores 0.8–6, well under this ceiling.
398
+ */
399
+ const SCORE_FLOOR_MAX = 10;
400
+ /**
401
+ * The relative floor must never starve a question of candidates: if it would
402
+ * leave fewer than this, backfill with the best-scoring ones it cut. The cost of
403
+ * under-serving is the agent calling explore again — a whole round-trip. See the
404
+ * backfill itself for the two strengths it runs at (thin vs. empty).
405
+ */
406
+ const SCORE_FLOOR_KEEP_MIN = 3;
407
+ // ── Score-proportional byte allocation (CG-12 / #1500) ─────────────────────
408
+ //
409
+ // The score floor above decides WHICH files reach the response. This decides how
410
+ // the byte envelope is SPLIT among them — and until this existed, it wasn't
411
+ // really decided at all: every admitted file was capped at the same
412
+ // `maxCharsPerFile`, and the whole-file rule handed anything under
413
+ // `maxCharsPerFile * 3` its entire contents. So allocation followed FILE SIZE,
414
+ // not relevance. On this repo's own "how does explore allocate its output budget
415
+ // across files", `src/mcp/tools.ts` (score 41, 4x the graph mass, 3x the distinct
416
+ // term hits — it literally holds the allocator) was clipped at 3,800 while a
417
+ // score-18 file shipped whole at 5,672 and took 51% of the envelope, purely for
418
+ // being small. On the #1500 Go fixture, two generated CRUD files shipped whole at
419
+ // ~4.5K each and consumed the tier's 4 file slots, so `BuildPayslip` — the
420
+ // hand-written half of "create and calculate payslips" — never appeared at all.
421
+ //
422
+ // The replacement: reserve each file a share of the envelope proportional to what
423
+ // it is worth, up front, before anything renders. Three consequences:
424
+ //
425
+ // 1. A reservation is a GUARANTEE, not a race. The old loop spent the envelope
426
+ // first-come-first-served in rank order, so the top two files could exhaust
427
+ // it and every later file hit a `budget-90pct` skip regardless of merit.
428
+ // 2. A file below the cliff gets ZERO source — its path, symbols and line
429
+ // numbers only. It costs ~100 chars instead of ~4,500, and (crucially) it
430
+ // does not consume a `maxFiles` slot, so the slot goes to a file that earns
431
+ // its bytes. This is the concentration lever.
432
+ // 3. The per-file cap stops being the primary guard. It survives only as
433
+ // `ALLOC_MAX_SHARE`, a safety valve against a single god-file — which the
434
+ // proportional split already bounds, since a file's share can't exceed its
435
+ // weight share.
436
+ exports.EXPLORE_ALLOCATION = {
437
+ /**
438
+ * A file whose weight is under this fraction of the top file's gets no source.
439
+ *
440
+ * Calibrated between the two shapes the fixtures pin: the #1500 generated CRUD
441
+ * lands at 10–11% of the top weight (penalised twice — once into the score by
442
+ * `rankPenalty`, once again here) and must cliff; a genuinely peripheral but
443
+ * hand-written flow file — `payslip_builder.go`, the direct callee of the
444
+ * workflow entry — lands at 25% and must NOT. Everything in between is a
445
+ * judgement call the agent can undo for ~0 cost, because a cliffed file is
446
+ * still NAMED in the response and one follow-up explore fetches it.
447
+ */
448
+ CLIFF_FRACTION: 0.15,
449
+ /**
450
+ * Ceiling on the cliff, in the same units as `SCORE_FLOOR_MAX` — and for the
451
+ * same reason. A file whose weight clears a full-strength direct match is never
452
+ * incidental, so no amount of concentration elsewhere may zero it: one
453
+ * overwhelming top file (a 99-scoring god-file among score-10 peers) otherwise
454
+ * puts the cliff at 14.9 and silences every peer the score floor had just
455
+ * deliberately admitted. The cliff is a RELATIVE prune of weak evidence, not a
456
+ * second admission gate — the score floor already owns admission.
457
+ */
458
+ CLIFF_MAX: SCORE_FLOOR_MAX,
459
+ /**
460
+ * Floor on a useful reservation — every admitted file gets this much before
461
+ * the proportional split divides the rest. Under it a slice can't hold one
462
+ * complete method, and a fragment is strictly worse than a pointer: it forces
463
+ * the Read this tool exists to prevent.
464
+ *
465
+ * It is a FLOOR, not a second cliff. Cliffing the starved file instead
466
+ * cascades: removing the smallest raises everyone else's share by so little
467
+ * that the next-smallest starves too, and a query with two dominant files ate
468
+ * six legitimately-ranked peers one at a time. Concentration is the relative
469
+ * cliff's job; this only keeps a served file's slice usable.
470
+ */
471
+ MIN_CHARS: 700,
472
+ /**
473
+ * Safety valve, as a fraction of the envelope. Not the primary guard any more —
474
+ * the proportional split is — so this only has to stop a pathological
475
+ * single-file response.
476
+ */
477
+ MAX_SHARE: 0.7,
478
+ /**
479
+ * Markdown overhead charged per rendered file (header + fences + blank lines),
480
+ * matching the render loop's own `+ 200` accounting. Held out of the pool
481
+ * before the split so the reservations plus their overhead fit the envelope —
482
+ * without this the last file's reservation is always the one that doesn't fit.
483
+ */
484
+ FILE_OVERHEAD: 200,
485
+ /**
486
+ * Flow-spine files are weighted up and are exempt from the cliff. Clipping the
487
+ * spine causes the Read fallback (it IS the answer to a flow question);
488
+ * clipping a peripheral file does not. This makes the existing advisory spine
489
+ * handling — `hasSpine`, `SPINE_CEILING` — strict at the allocation layer.
490
+ */
491
+ SPINE_WEIGHT_BOOST: 2,
492
+ /**
493
+ * Slack allowed on the whole-file rule: a file a little over its reservation
494
+ * still ships WHOLE rather than as clusters, because slicing off that last
495
+ * sliver saves ~1% of the envelope and costs a Read — the trade the whole-file
496
+ * rule exists to refuse. Proportional (with an absolute ceiling) because a
497
+ * "sliver" is relative: a flat 800 is 15% of a 5K reservation but 31% of a 2.5K
498
+ * one, and at the small end that overshoot is exactly what the file below then
499
+ * loses.
500
+ */
501
+ WHOLE_FILE_GRACE_FRACTION: 0.15,
502
+ WHOLE_FILE_GRACE_MAX: 800,
503
+ /**
504
+ * A reservation that already covers this fraction of a file BUYS THE WHOLE
505
+ * FILE (CG-21), even though the file is bigger than the reservation.
506
+ *
507
+ * The grace above is calibrated as a *sliver* — it only rescues a file that
508
+ * essentially fits. Below it there is a hole the render loop cannot fill:
509
+ * express's `lib/utils.js` (5,293 B) was the TOP-ranked file, reserved 3,870,
510
+ * declined the whole-file render at a 4,450 grace bound, and then spent 583 on
511
+ * a three-symbol cluster render. The other 3,287 chars of its reservation were
512
+ * neither redistributed nor delivered — the envelope shrank by a third against
513
+ * an unchanged budget and the agent Read the file back four times.
514
+ *
515
+ * So the rule is not "does the file fit the reservation" but "has the
516
+ * reservation already bought most of the file": at 0.6 the loop pays at most
517
+ * two-thirds of a reservation extra to avoid losing the whole thing, and it
518
+ * spends bytes it was going to spend anyway on a file that already earned
519
+ * them. Below the fraction the shortfall is real — the file is several times
520
+ * its reservation, clustering is the right answer, and the carry-forward
521
+ * (`reservedSoFar`/`sourceSpent` in the render loop) hands whatever it cannot
522
+ * spend to the next file down.
523
+ */
524
+ WHOLE_FILE_BUY_FRACTION: 0.6,
525
+ /**
526
+ * The buy rule's overshoot is funded from ONE pool for the whole response,
527
+ * sized as this fraction of the envelope — deliberately the same 15% as
528
+ * `WHOLE_FILE_GRACE_FRACTION`, one level up: the grace is a sliver of a
529
+ * FILE's reservation, this is a sliver of the RESPONSE's envelope.
530
+ *
531
+ * Per-file funding is the version that fails, and it fails the same way the
532
+ * bug being fixed does. The merit test is a RATIO, so wherever several files
533
+ * sit near it they all qualify, and N independent overshoots inflate the
534
+ * response until the render ceiling drops whatever is last. Measured on the
535
+ * #1500 payroll fixture: three files bought whole and `payslip_builder.go` —
536
+ * the file that computes the payslip the question asks about, rank #6 — was
537
+ * dropped entirely so three higher-ranked files could each ship their final
538
+ * sliver. A dropped section is strictly worse than a clustered one, so one
539
+ * shared pool, spent in rank order, is the bound that matters.
540
+ */
541
+ WHOLE_FILE_BUY_OVERSHOOT_FRACTION: 0.15,
542
+ };
543
+ /**
544
+ * Split `budget.maxOutputChars` across ranked candidates in proportion to
545
+ * relevance, with a hard relative cliff.
546
+ *
547
+ * `candidates` must arrive in FINAL RANK ORDER — `maxFiles` is applied to the
548
+ * survivors of the cliff, in that order, so cliffing genuinely hands a slot to
549
+ * the next file down rather than leaving it unused.
550
+ *
551
+ * Tier invariant (`getExploreOutputBudget`): a larger tier must never allow less
552
+ * per file than a smaller one. It holds here by construction — every bound is a
553
+ * fraction of `maxOutputChars` or of `maxCharsPerFile`, both monotonic across
554
+ * tiers — except `MIN_CHARS`, which is an absolute floor and so identical at
555
+ * every tier.
556
+ */
557
+ function allocateExploreBudget(candidates, budget, maxFiles) {
558
+ const A = exports.EXPLORE_ALLOCATION;
559
+ const empty = { allowances: new Map(), cliffed: [], cliffAt: 0, pool: 0 };
560
+ if (candidates.length === 0)
561
+ return empty;
562
+ // A non-finite weight is treated as no evidence rather than propagated: an
563
+ // Infinity score would otherwise make every share `Infinity/Infinity` = NaN and
564
+ // hand the render loop a NaN allowance. Scores are finite sums in the real
565
+ // pipeline, so this only has to fail safe.
566
+ const weightOf = (c) => {
567
+ const w = Math.max(0, c.score) * Math.max(0, Math.min(1, c.worth)) * (c.spine ? A.SPINE_WEIGHT_BOOST : 1);
568
+ return Number.isFinite(w) ? w : 0;
569
+ };
570
+ // Pinned files weigh at least as much as the strongest raw candidate: their
571
+ // score is whatever the stripped query happened to match (for a pure-path
572
+ // query, nearly nothing), and a proportional split on that would fund the
573
+ // named file worst of all. Floor of 1 covers the all-pinned/zero-score case.
574
+ const rawWeights = new Map(candidates.map((c) => [c.path, weightOf(c)]));
575
+ const topRaw = Math.max(...rawWeights.values());
576
+ const weights = new Map(candidates.map((c) => [
577
+ c.path,
578
+ c.pinned ? Math.max(rawWeights.get(c.path) ?? 0, topRaw, 1) : (rawWeights.get(c.path) ?? 0),
579
+ ]));
580
+ const topWeight = Math.max(...weights.values());
581
+ if (!(topWeight > 0))
582
+ return empty;
583
+ // Cliff over the WHOLE candidate list, before `maxFiles` — otherwise the file
584
+ // cap fills with cliff-bound files and the slot they free is never handed on.
585
+ const cliffAt = Math.min(topWeight * A.CLIFF_FRACTION, A.CLIFF_MAX);
586
+ const cliffed = [];
587
+ let admitted = [];
588
+ for (const c of candidates) {
589
+ if (!c.spine && !c.pinned && (weights.get(c.path) ?? 0) < cliffAt)
590
+ cliffed.push(c.path);
591
+ else
592
+ admitted.push(c);
593
+ }
594
+ // Never cliff every candidate: an empty response costs a whole round-trip.
595
+ if (admitted.length === 0) {
596
+ admitted = [candidates[0]];
597
+ cliffed.splice(cliffed.indexOf(candidates[0].path), 1);
598
+ }
599
+ for (const c of admitted.slice(maxFiles))
600
+ cliffed.push(c.path);
601
+ admitted = admitted.slice(0, maxFiles);
602
+ // Serve fewer files well rather than many badly: the envelope has to afford
603
+ // MIN_CHARS for everything admitted. When it can't, cliff the lowest-weight
604
+ // files (never a spine file, never the last one) in one deterministic trim —
605
+ // not one at a time, which is how the old starvation rule snowballed.
606
+ const affordable = Math.max(1, Math.floor(budget.maxOutputChars / (A.MIN_CHARS + A.FILE_OVERHEAD)));
607
+ if (admitted.length > affordable) {
608
+ const byWeight = [...admitted].sort((a, b) => (weights.get(b.path) ?? 0) - (weights.get(a.path) ?? 0));
609
+ const keep = new Set(byWeight.slice(0, affordable).map((c) => c.path));
610
+ for (const c of admitted)
611
+ if (c.spine || c.pinned)
612
+ keep.add(c.path);
613
+ for (const c of admitted)
614
+ if (!keep.has(c.path))
615
+ cliffed.push(c.path);
616
+ admitted = admitted.filter((c) => keep.has(c.path));
617
+ }
618
+ const allowances = new Map();
619
+ const pool = Math.max(0, budget.maxOutputChars - A.FILE_OVERHEAD * admitted.length);
620
+ const total = admitted.reduce((s, c) => s + (weights.get(c.path) ?? 0), 0);
621
+ if (total <= 0 || admitted.length === 0)
622
+ return { allowances, cliffed, cliffAt, pool };
623
+ // Everyone gets MIN_CHARS; the REMAINDER is what splits by weight. The floor
624
+ // is what keeps a diffuse survey question returning a useful spread, and the
625
+ // remainder is what concentrates a precise one — the top file's slice grows
626
+ // with its weight share, uncapped by any flat per-file limit.
627
+ const ceiling = Math.round(budget.maxOutputChars * A.MAX_SHARE);
628
+ const floors = Math.min(pool, A.MIN_CHARS * admitted.length);
629
+ const remainder = Math.max(0, pool - floors);
630
+ // Both parts FLOOR: a sum of rounded shares can exceed the remainder that fed
631
+ // it (by up to half a char per file), and the reservations must fit the pool
632
+ // exactly — the render loop spends them, so an over-allocation is an over-long
633
+ // response the hard ceiling then has to truncate. Flooring costs at most one
634
+ // char per file.
635
+ for (const c of admitted) {
636
+ const share = Math.floor(floors / admitted.length)
637
+ + Math.floor((remainder * (weights.get(c.path) ?? 0)) / total);
638
+ allowances.set(c.path, Math.min(share, ceiling));
639
+ }
640
+ return { allowances, cliffed, cliffAt, pool };
641
+ }
231
642
  /**
232
643
  * Whether `codegraph_explore` should prefix source lines with their line
233
644
  * numbers (cat -n style: `<num>\t<code>`).
@@ -316,6 +727,33 @@ function fileSectionHeader(filePath, suffix) {
316
727
  ? `${FILE_SECTION_PREFIX}${filePath}\`** — ${suffix}`
317
728
  : `${FILE_SECTION_PREFIX}${filePath}\`**`;
318
729
  }
730
+ /** Header of `codegraph_explore`'s trailing pointer list. */
731
+ const POINTER_HEADER = '**Not shown above — explore these names for their source**';
732
+ /** Most files the pointer list ever names one-per-line; the rest are a count. */
733
+ const POINTER_MAX_FILES = 10;
734
+ /**
735
+ * One pointer line: the file plus enough symbol names to make it NAMEABLE in a
736
+ * follow-up explore. Capped — an un-capped list ran to ~1.9K on the #1500
737
+ * fixture (12 generated CRUD symbols on one line), meta-text bought at the
738
+ * price of the source bytes this section exists to point away from.
739
+ */
740
+ function pointerLineFor(filePath, nodes) {
741
+ const POINTER_SYMBOLS = 6;
742
+ const named = nodes.filter((n) => n.kind !== 'import' && n.kind !== 'export');
743
+ const pool = named.length > 0 ? named : nodes;
744
+ const shown = pool.slice(0, POINTER_SYMBOLS);
745
+ const more = pool.length - shown.length;
746
+ const symbols = shown.map((n) => `${n.name}:${n.startLine}`).join(', ')
747
+ + (more > 0 ? `, +${more} more` : '');
748
+ return `- ${filePath}: ${symbols}`;
749
+ }
750
+ /**
751
+ * Emitted when the response was too full to carry ANY of its pointer list. It
752
+ * is the one line the epilogue floor is reserved for: the list itself can be
753
+ * traded away, but the agent must still be told that an uncovered area exists
754
+ * and that another explore — not a Read — is how to reach it.
755
+ */
756
+ const EPILOGUE_LOST_NOTE = '> (Trailing pointer list omitted for size. The source above is complete and verbatim — treat it as already Read. For anything this call did not cover, run another codegraph_explore with the specific names rather than reading those files.)';
319
757
  /**
320
758
  * Per-file staleness banner emitted at the top of a tool response when the
321
759
  * file watcher has pending events for files referenced by the response.
@@ -680,6 +1118,13 @@ class ToolHandler {
680
1118
  // The directory the server last searched for a default project. Surfaced in
681
1119
  // the "not initialized" error so users can see why detection missed.
682
1120
  defaultProjectHint = null;
1121
+ // Indexed sub-projects the engine's bounded down-scan saw below the search
1122
+ // base when no default project resolved (#1607). Listed in the "not
1123
+ // initialized" error so the fact is reachable through the protocol, not just
1124
+ // the host's stderr capture. Engine-maintained (initial resolve + throttled
1125
+ // retry) — tool calls themselves never scan.
1126
+ knownSubprojects = [];
1127
+ knownSubprojectsBase = null;
683
1128
  // Per-start-path cache of the git worktree/index mismatch (issue #155). The
684
1129
  // mismatch is a fixed property of (where the request came from → which
685
1130
  // .codegraph/ it resolves to), so the up-to-two `git rev-parse` spawns run
@@ -775,6 +1220,24 @@ class ToolHandler {
775
1220
  setDefaultProjectHint(searchedPath) {
776
1221
  this.defaultProjectHint = searchedPath;
777
1222
  }
1223
+ /**
1224
+ * Engine-only: record the indexed sub-projects the workspace down-scan saw
1225
+ * when it could not adopt a default project (#1606/#1607). An empty list
1226
+ * clears any previous note.
1227
+ */
1228
+ setKnownSubprojects(roots, base) {
1229
+ this.knownSubprojects = roots;
1230
+ this.knownSubprojectsBase = base;
1231
+ }
1232
+ /** One message line naming the indexed sub-projects, or '' when none known. */
1233
+ formatKnownSubprojects() {
1234
+ if (this.knownSubprojects.length === 0)
1235
+ return '';
1236
+ const base = this.knownSubprojectsBase;
1237
+ const rels = this.knownSubprojects.map((r) => (base ? (0, path_1.relative)(base, r) || '.' : r));
1238
+ return (`Indexed sub-projects were found below it: ${rels.join(', ')} — ` +
1239
+ 'pass one of them (absolute, or resolved against that directory) as projectPath.\n');
1240
+ }
778
1241
  /**
779
1242
  * Whether a default CodeGraph instance is available
780
1243
  */
@@ -892,6 +1355,7 @@ class ToolHandler {
892
1355
  const searched = this.defaultProjectHint ?? process.cwd();
893
1356
  throw new NotIndexedError('No CodeGraph project is loaded for this session.\n' +
894
1357
  `Searched for a .codegraph/ directory starting from: ${searched}\n` +
1358
+ this.formatKnownSubprojects() +
895
1359
  'Either the server root has no index of its own (e.g. a monorepo where only ' +
896
1360
  "sub-projects are indexed), or the MCP client launched the server outside your " +
897
1361
  'project without reporting the workspace root. Either way, target the project ' +
@@ -1089,6 +1553,68 @@ class ToolHandler {
1089
1553
  * Cost when nothing is pending — the common case — is one boolean check.
1090
1554
  * No I/O, no parsing of markdown beyond a per-pending-file substring scan.
1091
1555
  */
1556
+ driftCache = new Map();
1557
+ static DRIFT_TTL_MS = 2000;
1558
+ /**
1559
+ * On-disk drift check for a single indexed file (issue #1474). The code
1560
+ * renderers slice CURRENT bytes at INDEXED line ranges; when the file
1561
+ * changed after its last index sync those ranges can point at a DIFFERENT
1562
+ * symbol's code — served under the requested name with `isError: false`.
1563
+ * The watcher-based pending/degraded banners can't cover this for a
1564
+ * project reached via `projectPath` (cross-project instances have no
1565
+ * watcher, by construction), so freshness is verified here, at the point
1566
+ * of emission, from data the index already stores.
1567
+ *
1568
+ * Cheap and precise: one stat() per file (size + mtime, the same
1569
+ * comparison the sync fast path uses); only on a stat mismatch is the
1570
+ * content hashed (sha256, matching extraction's `hashContent`) so a
1571
+ * touch/checkout that rewrote identical bytes never false-positives.
1572
+ * Results are memoized briefly so one response rendering the same file in
1573
+ * several sections pays for the check once.
1574
+ *
1575
+ * Returns true when the on-disk file differs from what was indexed —
1576
+ * i.e. indexed line ranges for it are NOT trustworthy. Any failure
1577
+ * (missing files-table row, stat/read error) reports false: those cases
1578
+ * are handled by the existing not-found paths, and a wrong "stale" flag
1579
+ * would needlessly push the agent back to Read.
1580
+ */
1581
+ isFileStaleOnDisk(cg, relPath, content) {
1582
+ let root;
1583
+ try {
1584
+ root = cg.getProjectRoot();
1585
+ }
1586
+ catch {
1587
+ return false;
1588
+ }
1589
+ const key = `${root}\0${relPath}`;
1590
+ const now = Date.now();
1591
+ const hit = this.driftCache.get(key);
1592
+ if (hit && now - hit.at < ToolHandler.DRIFT_TTL_MS)
1593
+ return hit.stale;
1594
+ let stale = false;
1595
+ try {
1596
+ const rec = cg.getFile(relPath);
1597
+ const absPath = rec ? (0, utils_1.validatePathWithinRoot)(root, relPath) : null;
1598
+ if (rec && absPath && (0, fs_1.existsSync)(absPath)) {
1599
+ const st = (0, fs_1.statSync)(absPath);
1600
+ // Same freshness test as the sync fast path (extraction/index.ts):
1601
+ // equal size + equal floored mtime ⇒ unchanged, no read needed.
1602
+ if (st.size !== rec.size || Math.floor(st.mtimeMs) !== Math.floor(rec.modifiedAt)) {
1603
+ const data = content ?? (0, fs_1.readFileSync)(absPath, 'utf-8');
1604
+ // Must stay byte-identical to extraction's `hashContent` (sha256 over
1605
+ // the utf-8 string) — the identical-rewrite test in
1606
+ // mcp-stale-slice.test.ts pins the parity. Inlined (not imported)
1607
+ // to keep the extraction module off the MCP startup path.
1608
+ stale = (0, crypto_1.createHash)('sha256').update(data).digest('hex') !== rec.contentHash;
1609
+ }
1610
+ }
1611
+ }
1612
+ catch {
1613
+ stale = false;
1614
+ }
1615
+ this.driftCache.set(key, { at: now, stale });
1616
+ return stale;
1617
+ }
1092
1618
  withStalenessNotice(result, projectPath) {
1093
1619
  if (result.isError)
1094
1620
  return result;
@@ -1184,9 +1710,15 @@ class ToolHandler {
1184
1710
  return { ...result, content: [{ type: 'text', text: composed }, ...rest] };
1185
1711
  }
1186
1712
  /**
1187
- * Execute a tool by name
1713
+ * Execute a tool by name.
1714
+ *
1715
+ * `sessionState` is the CALLER's per-session explore history (CG-17). The
1716
+ * daemon shares one ToolHandler across every connected session, so this state
1717
+ * cannot live on the handler — each session owns one and hands it in, which is
1718
+ * what keeps two sessions on one daemon from ever seeing each other's calls.
1719
+ * Omit it (the CLI does) and explore behaves exactly as before, untracked.
1188
1720
  */
1189
- async execute(toolName, args) {
1721
+ async execute(toolName, args, sessionState) {
1190
1722
  try {
1191
1723
  // Block the first tool call on the engine's post-open reconcile so we
1192
1724
  // never serve rows for files deleted/edited while no MCP server was
@@ -1248,9 +1780,20 @@ class ToolHandler {
1248
1780
  // cross-cutting notices — worktree-index mismatch (#155) and per-file
1249
1781
  // staleness (#403) — which need the watched MAIN instance and so are
1250
1782
  // always applied here, never in the worker.
1251
- const result = (this.queryPool && this.queryPool.healthy && this.queryPool.ready)
1252
- ? await this.queryPool.run(toolName, args)
1253
- : await this.executeReadTool(toolName, args);
1783
+ //
1784
+ // Explore also carries the session's own call history down (CG-17) and its
1785
+ // emission record back up. Both travel as plain properties — on the args
1786
+ // object down, on the ToolResult up — because either leg may cross a
1787
+ // structured-clone boundary into a worker, where a closure or a handler
1788
+ // field could not follow.
1789
+ const dispatchArgs = this.withSessionView(toolName, args, sessionState);
1790
+ const raw = (this.queryPool && this.queryPool.healthy && this.queryPool.ready)
1791
+ ? await this.queryPool.run(toolName, dispatchArgs)
1792
+ : await this.executeReadTool(toolName, dispatchArgs);
1793
+ // Record + STRIP before anything else touches the result: the emission is
1794
+ // internal bookkeeping and must never reach the client, whether or not a
1795
+ // caller passed session state.
1796
+ const result = this.takeExploreEmission(raw, sessionState);
1254
1797
  const withWorktree = this.withWorktreeNotice(result, args.projectPath);
1255
1798
  return this.withStalenessNotice(withWorktree, args.projectPath);
1256
1799
  }
@@ -1270,6 +1813,50 @@ class ToolHandler {
1270
1813
  'continue without codegraph for this task.');
1271
1814
  }
1272
1815
  }
1816
+ /**
1817
+ * Attach the caller's session view to an explore call's args (CG-17), on a
1818
+ * COPY so the caller's object is never mutated. Nothing else sees it: a
1819
+ * non-explore tool, or a caller with no session state, gets the args
1820
+ * unchanged and pays nothing.
1821
+ *
1822
+ * A client that spells the internal key itself is stripped rather than
1823
+ * trusted — the view decides what source a later call may withhold, so it has
1824
+ * to come from the server's own record, never from the wire.
1825
+ */
1826
+ withSessionView(toolName, args, sessionState) {
1827
+ if (!(explore_session_state_1.EXPLORE_SESSION_VIEW_ARG in args) && (!sessionState || toolName !== 'codegraph_explore')) {
1828
+ return args;
1829
+ }
1830
+ const copy = { ...args };
1831
+ delete copy[explore_session_state_1.EXPLORE_SESSION_VIEW_ARG];
1832
+ if (sessionState && toolName === 'codegraph_explore') {
1833
+ copy[explore_session_state_1.EXPLORE_SESSION_VIEW_ARG] = sessionState.view();
1834
+ }
1835
+ return copy;
1836
+ }
1837
+ /**
1838
+ * Record an explore call's emission into the caller's session state and strip
1839
+ * it from the result (CG-17).
1840
+ *
1841
+ * Unconditional strip: the property is internal, so it comes off even when
1842
+ * there is no session state to record it into (the CLI path) — that is what
1843
+ * keeps the agent-facing response byte-identical. Recording is wrapped
1844
+ * because a bookkeeping bug must never fail a tool call that already
1845
+ * succeeded.
1846
+ */
1847
+ takeExploreEmission(result, sessionState) {
1848
+ const emission = result?.[explore_session_state_1.EXPLORE_EMISSION_KEY];
1849
+ if (emission === undefined)
1850
+ return result;
1851
+ delete result[explore_session_state_1.EXPLORE_EMISSION_KEY];
1852
+ if (sessionState) {
1853
+ try {
1854
+ sessionState.record(emission);
1855
+ }
1856
+ catch { /* bookkeeping only — never fail a served call */ }
1857
+ }
1858
+ return result;
1859
+ }
1273
1860
  /**
1274
1861
  * Run a single read tool to completion and return its raw {@link ToolResult},
1275
1862
  * classifying expected failures the same way {@link execute}'s catch does so
@@ -1342,9 +1929,10 @@ class ToolHandler {
1342
1929
  // Down-rank generated files within the FTS-returned set so a search
1343
1930
  // for "Send" surfaces the hand-written keeper before .pb.go stubs
1344
1931
  // that share the name. Stable: only reorders generated vs. not.
1932
+ const isGen = cg.generatedFilePredicate(results.map((r) => r.node.filePath));
1345
1933
  const ranked = [...results].sort((a, b) => {
1346
- const aGen = (0, generated_detection_1.isGeneratedFile)(a.node.filePath) ? 1 : 0;
1347
- const bGen = (0, generated_detection_1.isGeneratedFile)(b.node.filePath) ? 1 : 0;
1934
+ const aGen = isGen(a.node.filePath) ? 1 : 0;
1935
+ const bGen = isGen(b.node.filePath) ? 1 : 0;
1348
1936
  return aGen - bGen;
1349
1937
  });
1350
1938
  const formatted = this.formatSearchResults(ranked);
@@ -1730,6 +2318,13 @@ class ToolHandler {
1730
2318
  // fed only to the dynamic-dispatch-links scan below.
1731
2319
  const dynNamed = new Map();
1732
2320
  const DYN_KINDS = new Set(['constant', 'variable', 'field', 'property']);
2321
+ // Nodes resolved from a SHAPE-PRECISE token (camelCase / PascalCase /
2322
+ // snake_case / qualified) — the same test the gather path uses. It is the
2323
+ // difference between "the agent named this symbol" and "an ordinary English
2324
+ // word in a prose question collided with a callable", and it is what makes
2325
+ // the narrative-less return below safe (see `identityOnly`).
2326
+ const isPreciseToken = (x) => /[._$]|::|\//.test(x) || /[a-z][A-Z]/.test(x) || /^[A-Z]/.test(x);
2327
+ const preciseNamedIds = new Set();
1733
2328
  const hasHeuristicEdge = (id) => [...cg.getCallers(id), ...cg.getCallees(id)].some(({ edge }) => edge.provenance === 'heuristic');
1734
2329
  for (const t of tokens) {
1735
2330
  const hits = this.findAllSymbols(cg, t).nodes;
@@ -1747,10 +2342,13 @@ class ToolHandler {
1747
2342
  });
1748
2343
  const kept = pick.slice(0, 6);
1749
2344
  tokenNodes.set(t, kept.map((n) => n.id));
2345
+ const precise = isPreciseToken(t);
1750
2346
  for (const n of kept) {
1751
2347
  named.set(n.id, n);
1752
2348
  if (specific)
1753
2349
  uniqueNamedNodeIds.add(n.id);
2350
+ if (precise)
2351
+ preciseNamedIds.add(n.id);
1754
2352
  }
1755
2353
  // Same token, non-callable synth endpoints (capped, precision-gated on an
1756
2354
  // actual heuristic edge so plain config constants never qualify).
@@ -1764,6 +2362,8 @@ class ToolHandler {
1764
2362
  continue;
1765
2363
  if (hasHeuristicEdge(n.id)) {
1766
2364
  dynNamed.set(n.id, n);
2365
+ if (precise)
2366
+ preciseNamedIds.add(n.id);
1767
2367
  tokenDyn++;
1768
2368
  }
1769
2369
  if (dynNamed.size >= 12 || tokenDyn >= 4)
@@ -1802,6 +2402,35 @@ class ToolHandler {
1802
2402
  }
1803
2403
  return synthLines;
1804
2404
  };
2405
+ /**
2406
+ * No narrative to print — but the agent still NAMED symbols, and their
2407
+ * identity is a separate output from the prose (CG-38).
2408
+ *
2409
+ * `namedNodeIds` is not decoration: downstream it injects the named def into
2410
+ * the file's cluster ranges and ranks it importance 9, which is the whole
2411
+ * mechanism behind "a symbol the agent named renders" (the assembler's
2412
+ * named-def injection). Returning EMPTY here threw that away whenever the
2413
+ * named symbols happened not to form a call chain — two sibling closures in
2414
+ * one factory (`queueMessage` / `flushQueuedMessages`, neither calling the
2415
+ * other) produce no chain, no synth hop and no dispatch boundary, so BOTH
2416
+ * defs lost importance 9 and the file rendered from its head instead: the
2417
+ * agent got the `QueuedMessage` interface at L70 and had to Read the file
2418
+ * for the functions at L1087/L1102 it had asked for by name.
2419
+ *
2420
+ * Restricted to SHAPE-PRECISE tokens. With a narrative present the prose is
2421
+ * itself corroboration that the resolution was right, so that path keeps
2422
+ * every named id as before; with nothing corroborating it, only an
2423
+ * unambiguous symbol reference may promote — an English word in a prose
2424
+ * question that happens to exact-match a callable must not earn importance 9.
2425
+ * Same distinction, same test, as the gather path's `isPreciseToken`.
2426
+ */
2427
+ const identityOnly = () => (preciseNamedIds.size === 0 ? EMPTY : {
2428
+ text: '',
2429
+ pathNodeIds: new Set(),
2430
+ namedNodeIds: new Set(preciseNamedIds),
2431
+ uniqueNamedNodeIds: new Set([...uniqueNamedNodeIds].filter((id) => preciseNamedIds.has(id))),
2432
+ spineCallSites: new Map(),
2433
+ });
1805
2434
  if (named.size < 2) {
1806
2435
  // <2 CALLABLES resolved. Two recoveries before giving up: (1) synthesized
1807
2436
  // edges among named CONSTANT/VARIABLE endpoints — RTK thunk→thunk is
@@ -1811,7 +2440,7 @@ class ToolHandler {
1811
2440
  const synthLines = collectSynthLinks(null);
1812
2441
  const boundaries = named.size === 0 ? '' : (this.buildDynamicBoundaries(cg, [...named.values()], named) || '');
1813
2442
  if (synthLines.length === 0 && !boundaries)
1814
- return EMPTY;
2443
+ return identityOnly();
1815
2444
  const out = [];
1816
2445
  if (synthLines.length)
1817
2446
  out.push('**Dynamic-dispatch links among your symbols**', '(synthesized — the indirect hops grep/Read would reconstruct; the `@file:line` is the wiring site)', '', ...synthLines, '');
@@ -1947,7 +2576,7 @@ class ToolHandler {
1947
2576
  // hop still surfaces — too short for Flow, but #687-visible here.
1948
2577
  const synthLines = collectSynthLinks(hasMain ? (e) => pathIds.has(e.source) && pathIds.has(e.target) : null);
1949
2578
  if (!hasMain && synthLines.length === 0 && !boundaryText && !polyText)
1950
- return EMPTY;
2579
+ return identityOnly();
1951
2580
  const out = [];
1952
2581
  if (hasMain) {
1953
2582
  out.push('**Flow (call path among the symbols you queried)**', '');
@@ -2256,7 +2885,7 @@ class ToolHandler {
2256
2885
  const ROOT_CAP = 5; // only the symbols the query actually targeted
2257
2886
  const FILE_CAP = 4; // caller files listed per symbol before "+N more"
2258
2887
  const MEANINGFUL = new Set([
2259
- 'function', 'method', 'class', 'interface', 'struct', 'trait', 'protocol',
2888
+ 'function', 'method', 'class', 'interface', 'struct', 'union', 'trait', 'protocol',
2260
2889
  'enum', 'type_alias', 'component', 'constant', 'variable', 'property', 'field',
2261
2890
  ]);
2262
2891
  const rel = (p) => p.replace(/\\/g, '/');
@@ -2291,7 +2920,7 @@ class ToolHandler {
2291
2920
  const where = nonTest.length > 0 ? ` in ${shown}${more}` : '';
2292
2921
  const tests = testFiles.length > 0
2293
2922
  ? `; tests: ${testFiles.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ')}${testFiles.length > FILE_CAP ? ` +${testFiles.length - FILE_CAP}` : ''}`
2294
- : '; ⚠️ no covering tests found';
2923
+ : this.indirectTestNote(cg, uniq, rel);
2295
2924
  entries.push(`- \`${root.name}\` (${rel(root.filePath)}:${root.startLine}) — ${uniq.length} caller${uniq.length === 1 ? '' : 's'}${where}${tests}`);
2296
2925
  }
2297
2926
  if (entries.length === 0)
@@ -2303,6 +2932,59 @@ class ToolHandler {
2303
2932
  '',
2304
2933
  ].join('\n');
2305
2934
  }
2935
+ /**
2936
+ * Test-coverage note for a blast-radius entry whose DIRECT callers include no
2937
+ * test file. A helper called only by production code can still be exercised
2938
+ * by tests further up the caller chain (#1475: 40% of directly-unflagged
2939
+ * symbols had a test within 2-3 hops), so walk up to 2 more hops before
2940
+ * claiming anything — and even then claim only what was measured.
2941
+ */
2942
+ indirectTestNote(cg, directCallers, rel) {
2943
+ const MAX_HOPS = 3; // direct callers are hop 1
2944
+ const BUDGET = 64; // getCallers lookups per entry — bounds god-fan-in symbols
2945
+ const FILE_CAP = 2;
2946
+ let budget = BUDGET;
2947
+ const visited = new Set(directCallers.map((n) => n.id));
2948
+ let frontier = directCallers;
2949
+ for (let hop = 2; hop <= MAX_HOPS && frontier.length > 0 && budget > 0; hop++) {
2950
+ const next = [];
2951
+ const found = new Set();
2952
+ for (const node of frontier) {
2953
+ if (budget-- <= 0)
2954
+ break;
2955
+ let callers = [];
2956
+ try {
2957
+ callers = cg.getCallers(node.id);
2958
+ }
2959
+ catch {
2960
+ continue;
2961
+ }
2962
+ for (const c of callers) {
2963
+ const n = c?.node;
2964
+ if (!n || visited.has(n.id))
2965
+ continue;
2966
+ visited.add(n.id);
2967
+ const f = rel(n.filePath);
2968
+ if ((0, query_utils_1.isTestFile)(f))
2969
+ found.add(f);
2970
+ else
2971
+ next.push(n);
2972
+ }
2973
+ }
2974
+ if (found.size > 0) {
2975
+ const files = [...found];
2976
+ const shown = files.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ');
2977
+ const more = files.length > FILE_CAP ? ` +${files.length - FILE_CAP}` : '';
2978
+ return `; tested via callers: ${shown}${more}`;
2979
+ }
2980
+ frontier = next;
2981
+ }
2982
+ // Budget exhaustion means hops 2-3 weren't fully searched — fall back to
2983
+ // the weaker claim that IS established by the direct-caller check.
2984
+ return budget > 0
2985
+ ? `; no tests found within ${MAX_HOPS} caller hops`
2986
+ : '; no test calls this directly';
2987
+ }
2306
2988
  /**
2307
2989
  * Graph-connectivity relevance via Random-Walk-with-Restart (personalized
2308
2990
  * PageRank) from the query's matched SEED nodes over the call/reference graph.
@@ -2409,25 +3091,122 @@ class ToolHandler {
2409
3091
  // largest-tier defaults if stats aren't available, which preserves
2410
3092
  // pre-#185 behavior for callers that hit the rare stats failure.
2411
3093
  let budget;
3094
+ let indexedFileCount = -1;
2412
3095
  try {
2413
- budget = getExploreOutputBudget(cg.getStats().fileCount);
3096
+ indexedFileCount = cg.getStats().fileCount;
3097
+ budget = getExploreOutputBudget(indexedFileCount);
2414
3098
  }
2415
3099
  catch {
2416
3100
  budget = getExploreOutputBudget(Infinity);
2417
3101
  }
2418
3102
  const maxFiles = (0, utils_1.clamp)(args.maxFiles || budget.defaultMaxFiles, 1, 20);
3103
+ // File paths named in the query become PINNED files: guaranteed admission,
3104
+ // top of the rank order, funded first — and their span is REMOVED from the
3105
+ // matching query. Runs on the RAW query (normalizeQuerySpelling strips
3106
+ // `/digits` tails, which would mangle numeric path segments). Without this,
3107
+ // a SvelteKit path like `runs/[runId]/+page.svelte` was shredded by the
3108
+ // seeding tokenizer (splits on brackets → `runId` seeded as a "named
3109
+ // symbol") and by FTS (`page`/`runs` fragments admitted every sibling
3110
+ // `+page.svelte`), starving the very files the agent asked for.
3111
+ let pinnedFiles = [];
3112
+ let unresolvedPathSpans = [];
3113
+ let matchQuery = query;
3114
+ if ((0, query_paths_1.queryMightContainPaths)(rawQuery)) {
3115
+ try {
3116
+ const extraction = (0, query_paths_1.extractQueryPaths)(rawQuery, cg.getFiles().map((f) => f.path), { maxPins: maxFiles });
3117
+ if (extraction.pinnedFiles.length > 0 || extraction.unresolvedPathSpans.length > 0) {
3118
+ pinnedFiles = extraction.pinnedFiles;
3119
+ unresolvedPathSpans = extraction.unresolvedPathSpans;
3120
+ matchQuery = normalizeQuerySpelling(extraction.strippedQuery);
3121
+ }
3122
+ }
3123
+ catch { /* path pinning must never fail an explore call */ }
3124
+ }
3125
+ const pinnedSet = new Set(pinnedFiles);
3126
+ const pinnedOrder = new Map(pinnedFiles.map((p, i) => [p, i]));
3127
+ // Per-file allocation diagnostic (CG-4). `null` unless CODEGRAPH_EXPLORE_DEBUG
3128
+ // is set — every `diag?.` below is then a no-op and the response is
3129
+ // byte-identical. It only OBSERVES: it must never feed back into rendering.
3130
+ const diag = explore_diagnostics_1.ExploreDiagnostics.start(query, projectRoot, budget, maxFiles, indexedFileCount);
3131
+ // What this session has already been served for THIS project (CG-17), and
3132
+ // whether this call may act on it (CG-18). Dedup is off on the session's
3133
+ // first call by construction — there is nothing to point back AT — and off
3134
+ // entirely under `CODEGRAPH_EXPLORE_DEDUP=0`.
3135
+ const priorCalls = (0, explore_session_state_1.viewForProject)((0, explore_session_state_1.readExploreSessionView)(args), projectRoot);
3136
+ diag?.noteSession(priorCalls);
3137
+ const dedupEnabled = (0, explore_dedup_1.exploreDedupEnabled)() && (priorCalls?.calls.length ?? 0) > 0;
3138
+ // Cross-call dedup accounting (CG-18). `newSourceChars` is the load-bearing
3139
+ // one: a response whose source is ENTIRELY back-references is the shape that
3140
+ // reads as a failure, so the loop keeps the top suppressed file's real
3141
+ // section in hand and restores it if nothing new made it in — see
3142
+ // `suppressedFallback` below.
3143
+ let newSourceChars = 0;
3144
+ const backReferencedFiles = [];
3145
+ // What this call ends up emitting, per file — the record handed back to the
3146
+ // session state on the main thread. Filled by every render path below, then
3147
+ // filtered to the files that SURVIVE the final hard-ceiling cut, so the
3148
+ // record is what the agent actually received rather than what the loop
3149
+ // hoped to send.
3150
+ //
3151
+ // Back-referenced spans are recorded too, with zero bytes (CG-18): the
3152
+ // record means "source the agent HOLDS for this file", not "bytes this call
3153
+ // spent". Re-recording them refreshes them inside the retained-call window,
3154
+ // so a file pointed at across many calls doesn't age out of the history and
3155
+ // get re-served for no reason.
3156
+ const emittedByFile = new Map();
3157
+ const noteEmitted = (fp, ranges, bytes, fingerprint) => {
3158
+ const existing = emittedByFile.get(fp);
3159
+ if (existing) {
3160
+ existing.ranges.push(...ranges);
3161
+ existing.bytes += bytes;
3162
+ if (fingerprint)
3163
+ existing.fingerprint = fingerprint;
3164
+ }
3165
+ else {
3166
+ emittedByFile.set(fp, { ranges: [...ranges], bytes, fingerprint });
3167
+ }
3168
+ };
2419
3169
  // Step 1: Find relevant context with generous parameters.
2420
3170
  // Use a large maxNodes budget — explore has its own 35k char output limit
2421
3171
  // that prevents context bloat, so more nodes just means better coverage
2422
3172
  // across entry points (especially for large files like Svelte components).
2423
- const subgraph = await cg.findRelevantContext(query, {
3173
+ // Matching runs on the path-stripped query; `query` stays for display.
3174
+ const subgraph = await cg.findRelevantContext(matchQuery, {
2424
3175
  searchLimit: 8,
2425
3176
  traversalDepth: 3,
2426
3177
  maxNodes: 200,
2427
3178
  minScore: 0.2,
2428
3179
  });
3180
+ // Pinned files' symbols enter the gather unconditionally — the agent named
3181
+ // the file itself, so its contents ARE the answer regardless of what the
3182
+ // stripped query text matched (which, for a pure-path query, is nothing).
3183
+ const PINNED_FILE_NODE_CAP = 300;
3184
+ for (const fp of pinnedFiles) {
3185
+ let fileNodes = [];
3186
+ try {
3187
+ fileNodes = cg.getNodesInFile(fp);
3188
+ }
3189
+ catch {
3190
+ continue;
3191
+ }
3192
+ fileNodes
3193
+ .filter((n) => n.kind !== 'file' && n.kind !== 'import' && n.kind !== 'export')
3194
+ .sort((a, b) => a.startLine - b.startLine)
3195
+ .slice(0, PINNED_FILE_NODE_CAP)
3196
+ .forEach((n) => { if (!subgraph.nodes.has(n.id))
3197
+ subgraph.nodes.set(n.id, n); });
3198
+ }
2429
3199
  if (subgraph.nodes.size === 0) {
2430
- return this.textResult(`No relevant code found for "${query}"`);
3200
+ diag?.finishEmpty('no relevant code found — empty subgraph');
3201
+ const missNote = unresolvedPathSpans.length > 0
3202
+ ? ` (no indexed file uniquely matches ${unresolvedPathSpans.map((s) => `\`${s}\``).join(', ')})`
3203
+ : '';
3204
+ const empty = `No relevant code found for "${query}"${missNote}`;
3205
+ // Still an explore call, so it is still recorded: an empty answer spends a
3206
+ // call against the tier budget even though it emits no source.
3207
+ return this.exploreResult(empty, {
3208
+ projectRoot, query, files: [], sourceBytes: 0, responseBytes: empty.length,
3209
+ });
2431
3210
  }
2432
3211
  // Graph-aware glue: findRelevantContext builds the subgraph from name/text
2433
3212
  // search, so a method that BRIDGES named symbols — e.g. App.tsx's
@@ -2483,9 +3262,19 @@ class ToolHandler {
2483
3262
  // and crowd out the real answer file (grpc's `dialoptions.go`). Corroborated
2484
3263
  // overloads (the query also named the type) all earn it. (#1064)
2485
3264
  const tierSeedIds = new Set();
3265
+ // Files declaring a TYPE the query named by name — the counter-case guard
3266
+ // for the declaration-only penalty (CG-28). Populated in the token loop.
3267
+ const namedTypeFiles = new Set();
2486
3268
  {
2487
3269
  const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro|erl|hrl)$/i;
2488
3270
  const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
3271
+ // Variables/constants seed too: in Svelte/React a `$state` variable
3272
+ // (`chatAtBottom`, `feedAtBottom`) is exactly the kind of symbol an agent
3273
+ // names in a query, and the exact-name search channel already returns
3274
+ // them — only this seeding tier was callable-only. The NL-stopword guard
3275
+ // below applies unchanged, so bare English words still can't seed a
3276
+ // same-named local. Callables keep priority via the body-size sort.
3277
+ const SEEDABLE = new Set([...CALLABLE, 'variable', 'constant']);
2489
3278
  const isTestPath = (p) => /(^|\/)(tests?|specs?|__tests__|testdata|mocks?|fixtures?)\//i.test(p) || /\.(test|spec)\.[a-z]+$/i.test(p);
2490
3279
  const bodyLines = (n) => Math.max(0, (n.endLine ?? n.startLine) - n.startLine);
2491
3280
  const callerCount = (n) => { try {
@@ -2494,7 +3283,7 @@ class ToolHandler {
2494
3283
  catch {
2495
3284
  return 0;
2496
3285
  } };
2497
- const tokens = [...new Set(query.split(/[\s,()[\]]+/)
3286
+ const tokens = [...new Set(matchQuery.split(/[\s,()[\]]+/)
2498
3287
  .map((t) => t.replace(FILE_EXT, '').trim())
2499
3288
  .filter((t) => t.length >= 3 && /^[A-Za-z_$][\w$]*(?:(?:::|\.)[\w$]+)*$/.test(t)))].slice(0, 16);
2500
3289
  // PascalCase tokens in the query are type/file disambiguators — when the
@@ -2551,25 +3340,42 @@ class ToolHandler {
2551
3340
  // codegraph_node's findSymbolMatches.) Qualified tokens keep findAllSymbols.
2552
3341
  const isQual = /[.\/]|::/.test(t);
2553
3342
  const raw = isQual ? this.findAllSymbols(cg, t).nodes : cg.getNodesByName(t);
3343
+ // A query that NAMES a declared type is a question ABOUT that type, and
3344
+ // must still reach its declaration file at full weight — so record the
3345
+ // files those declarations live in and exempt them from the
3346
+ // declaration-only penalty below (CG-28). Only PRECISE tokens count, by
3347
+ // the same NL-stopword reasoning as the seeding above: "…the file body…"
3348
+ // must not exempt a `Body` interface it never meant to name. Kept
3349
+ // separate from `namedSeedIds`, which is callable-only by construction —
3350
+ // a type never becomes a named seed, so it cannot be the guard here.
3351
+ if (isPreciseToken(t)) {
3352
+ for (const n of raw) {
3353
+ if (DECLARATION_KINDS.has(n.kind) && n.name.toLowerCase() === t.toLowerCase()) {
3354
+ namedTypeFiles.add(n.filePath);
3355
+ }
3356
+ }
3357
+ }
2554
3358
  let cands = raw
2555
- .filter((n) => CALLABLE.has(n.kind) && !isTestPath(n.filePath))
3359
+ .filter((n) => SEEDABLE.has(n.kind) && !isTestPath(n.filePath))
2556
3360
  .sort((a, b) => (bodyLines(b) > 1 ? 1 : 0) - (bodyLines(a) > 1 ? 1 : 0) || bodyLines(b) - bodyLines(a));
2557
3361
  // Field-name seeding fallback (#1196): a camelCase token that names NO
2558
3362
  // definition of its own is usually an object-literal key / API field
2559
3363
  // (`profileInfo`) — no node exists, so it contributed zero seeds and
2560
3364
  // the files that DEFINE it (`getProfileInfoV2` in profileController)
2561
- // never surfaced. Seed its camel-infix definers instead: callables
2562
- // whose name contains the token at a hump boundary or as a prefix.
3365
+ // never surfaced. Seed its camel-infix definers instead: seedable
3366
+ // symbols (callables + variables — `atBottom` must reach the `$state`
3367
+ // variables `feedAtBottom`/`chatAtBottom`) whose name contains the
3368
+ // token at a hump boundary or as a prefix.
2563
3369
  // Exact-empty + camel-shaped only (bare words keep the NL-stopword
2564
3370
  // guard below), shortest-first, capped so a hot infix can't flood.
2565
3371
  if (cands.length === 0 && !isQual && /[a-z][A-Z]/.test(t)) {
2566
3372
  const lcToken = t.toLowerCase();
2567
3373
  cands = cg
2568
3374
  .getNodesByNameSubstring(t, {
2569
- kinds: ['function', 'method', 'component'],
3375
+ kinds: ['function', 'method', 'component', 'variable', 'constant'],
2570
3376
  limit: 60,
2571
3377
  })
2572
- .filter((n) => CALLABLE.has(n.kind) && !isTestPath(n.filePath))
3378
+ .filter((n) => SEEDABLE.has(n.kind) && !isTestPath(n.filePath))
2573
3379
  .filter((n) => {
2574
3380
  const idx = n.name.toLowerCase().indexOf(lcToken);
2575
3381
  if (idx < 0)
@@ -2629,6 +3435,8 @@ class ToolHandler {
2629
3435
  }
2630
3436
  }
2631
3437
  // Step 2: Group nodes by file, score by relevance
3438
+ // `peripheral` accumulates separately so it can be capped — see
3439
+ // PERIPHERAL_SCORE_CAP; it is folded into `score` once the loop is done.
2632
3440
  const fileGroups = new Map();
2633
3441
  const entryNodeIds = new Set([...subgraph.roots, ...namedSeedIds]);
2634
3442
  // Build a set of nodes directly connected to entry points (depth 1)
@@ -2639,6 +3447,49 @@ class ToolHandler {
2639
3447
  if (entryNodeIds.has(edge.target))
2640
3448
  connectedToEntry.add(edge.source);
2641
3449
  }
3450
+ // Usage degree within the subgraph, for the weak-kind isolation test below.
3451
+ // Free (the edges are already in hand) and it answers most cases; only a
3452
+ // weak-kind node that looks isolated HERE pays for a DB probe.
3453
+ const subgraphUsageDegree = new Map();
3454
+ for (const edge of subgraph.edges) {
3455
+ if (!RELEVANCE_USAGE_EDGES.has(edge.kind) || edge.source === edge.target)
3456
+ continue;
3457
+ subgraphUsageDegree.set(edge.source, (subgraphUsageDegree.get(edge.source) ?? 0) + 1);
3458
+ subgraphUsageDegree.set(edge.target, (subgraphUsageDegree.get(edge.target) ?? 0) + 1);
3459
+ }
3460
+ /**
3461
+ * Relevance weight for one matched symbol: its NodeKind, further discounted
3462
+ * when it is a weak kind that NOTHING uses. The DB probe (full-graph, since
3463
+ * a usage can sit outside the traversal) is paid for only by weak-kind
3464
+ * symbols in the top two tiers — the ones whose weight can carry a whole
3465
+ * file. A `connectedToEntry` or peripheral node is worth <= 3 either way, so
3466
+ * probing it would buy nothing.
3467
+ */
3468
+ const isolationCache = new Map();
3469
+ const isUsageIsolated = (node) => {
3470
+ if ((subgraphUsageDegree.get(node.id) ?? 0) > 0)
3471
+ return false;
3472
+ const cached = isolationCache.get(node.id);
3473
+ if (cached !== undefined)
3474
+ return cached;
3475
+ let isolated = true;
3476
+ try {
3477
+ const used = (e) => RELEVANCE_USAGE_EDGES.has(e.kind);
3478
+ isolated = !cg.getIncomingEdges(node.id).some(used)
3479
+ && !cg.getOutgoingEdges(node.id).some(used);
3480
+ }
3481
+ catch {
3482
+ isolated = false; // a probe failure must not manufacture a penalty
3483
+ }
3484
+ isolationCache.set(node.id, isolated);
3485
+ return isolated;
3486
+ };
3487
+ const relevanceWeight = (node, probeIsolation) => {
3488
+ const weight = exports.RELEVANCE_KIND_WEIGHT[node.kind] ?? DEFAULT_RELEVANCE_KIND_WEIGHT;
3489
+ if (!probeIsolation || !WEAK_RELEVANCE_KINDS.has(node.kind))
3490
+ return weight;
3491
+ return isUsageIsolated(node) ? ISOLATED_WEAK_KIND_WEIGHT : weight;
3492
+ };
2642
3493
  // CHANGE SURFACE (#1064): a named method's signature types — its parameter
2643
3494
  // and return types — are part of what you'd edit to "add a parameter to X",
2644
3495
  // yet they can be lexically dissimilar to the query ("add a parameter to
@@ -2652,7 +3503,7 @@ class ToolHandler {
2652
3503
  // displaces a flow-central file. Bounded: only the few named seeds, only the
2653
3504
  // types in their signatures.
2654
3505
  const CALLABLE_KINDS = new Set(['method', 'function', 'component', 'constructor']);
2655
- const TYPE_KINDS = new Set(['class', 'struct', 'interface', 'trait', 'protocol', 'enum', 'type_alias']);
3506
+ const TYPE_KINDS = new Set(['class', 'struct', 'union', 'interface', 'trait', 'protocol', 'enum', 'type_alias']);
2656
3507
  const SIG_EDGE = new Set(['references', 'type_of', 'returns']);
2657
3508
  const changeSurfaceCandidates = [];
2658
3509
  const seenChangeSurface = new Set();
@@ -2689,7 +3540,7 @@ class ToolHandler {
2689
3540
  // unbidden. The key still appears in the flow/symbol listing above.
2690
3541
  if ((0, utils_1.isConfigLeafNode)(node))
2691
3542
  continue;
2692
- const group = fileGroups.get(node.filePath) || { nodes: [], score: 0 };
3543
+ const group = fileGroups.get(node.filePath) || { nodes: [], score: 0, peripheral: 0 };
2693
3544
  group.nodes.push(node);
2694
3545
  // Score: a NAMED-SEED node (a symbol the agent named that FTS missed, now
2695
3546
  // injected) is worth far more than a mere reference — its file is where the
@@ -2697,29 +3548,42 @@ class ToolHandler {
2697
3548
  // (Combine.swift references request/task → score 23 from connected nodes)
2698
3549
  // outranks the file that DEFINES a named symbol (Validation.swift's
2699
3550
  // `validate` → 10) and steals its render slot. Definition ≫ reference.
3551
+ //
3552
+ // Each tier is then scaled by WHAT was matched (RELEVANCE_KIND_WEIGHT): the
3553
+ // tier says how the symbol reached us, the kind weight says whether the
3554
+ // match is evidence. A file whose only claim is an unused local `explore`
3555
+ // constant is a name collision, not an answer (#1500).
2700
3556
  if (namedSeedIds.has(node.id)) {
2701
- group.score += 50;
3557
+ group.score += 50 * relevanceWeight(node, true);
2702
3558
  }
2703
3559
  else if (entryNodeIds.has(node.id)) {
2704
- group.score += 10;
3560
+ group.score += 10 * relevanceWeight(node, true);
2705
3561
  }
2706
3562
  else if (connectedToEntry.has(node.id)) {
2707
- group.score += 3;
3563
+ group.score += 3 * relevanceWeight(node, false);
2708
3564
  }
2709
3565
  else {
2710
- group.score += 1;
3566
+ // Peripheral: in the subgraph but ≥2 hops from anything the query
3567
+ // matched. Accumulated separately and capped below, so a file cannot
3568
+ // buy relevance with size alone.
3569
+ group.peripheral += relevanceWeight(node, false);
2711
3570
  }
2712
3571
  fileGroups.set(node.filePath, group);
2713
3572
  }
2714
- // Only include files that have entry points or nodes directly connected to entry points
2715
- let relevantFiles = [...fileGroups.entries()].filter(([, group]) => group.score >= 3);
2716
- // Extract query terms for relevance checking
2717
- const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length >= 3);
2718
- // Test/spec/icon/i18n file detector — used both for the pre-sort hard
2719
- // filter (tiny tier) and the comparator deprioritization (all tiers).
3573
+ // Extract query terms for relevance checking (path-stripped: a pinned
3574
+ // file's own path fragments must not count as "term hits" everywhere)
3575
+ const queryTerms = matchQuery.toLowerCase().split(/\s+/).filter(t => t.length >= 3);
3576
+ // Test/spec/icon/i18n file detector — used by the pre-floor hard filter, the
3577
+ // rank penalty, and the comparator deprioritization.
3578
+ //
3579
+ // The directory pattern is anchored at `^` as well as `/`: a repo-ROOT
3580
+ // `test/` or `spec/` directory (express, cobra, and most of npm/Go) produced
3581
+ // paths like `test/express.raw.js`, which the old leading-`/` form could
3582
+ // never match — so express's routing question spent 59% of its envelope on
3583
+ // three test files while `lib/router/index.js` never rendered.
2720
3584
  const isLowValue = (p) => {
2721
3585
  const lp = p.toLowerCase();
2722
- return (/\/(tests?|__tests?__|spec)\//.test(lp) ||
3586
+ return (/(?:^|\/)(tests?|__tests?__|specs?)\//.test(lp) ||
2723
3587
  /_test\.go$/.test(lp) ||
2724
3588
  /(?:^|\/)test_[^/]+\.py$/.test(lp) ||
2725
3589
  /_test\.py$/.test(lp) ||
@@ -2733,7 +3597,45 @@ class ToolHandler {
2733
3597
  /\bicons?\b/.test(lp) ||
2734
3598
  /\bi18n\b/.test(lp));
2735
3599
  };
2736
- // Hard-exclude test/spec files (ALL tiers, not just tiny). One slipped test
3600
+ // One DB probe over every file the query touched, then O(1) per lookup.
3601
+ // Unions the index-time content-banner flag (CG-5) with the filename
3602
+ // convention, so a Go monorepo's generated CRUD (`payroll.go` carrying a
3603
+ // DO-NOT-EDIT banner and nothing in its name) down-ranks the same way
3604
+ // `.pb.go` always has (#1500). Covers the whole subgraph, not just the
3605
+ // grouped files, because the graph-mass penalty below is keyed on it too.
3606
+ const penaltyCandidates = new Set([
3607
+ ...fileGroups.keys(),
3608
+ ...[...subgraph.nodes.values()].map((n) => n.filePath),
3609
+ ]);
3610
+ const isGeneratedCandidate = cg.generatedFilePredicate(penaltyCandidates);
3611
+ // Second bounded probe over the same set: files declaring nothing but types
3612
+ // that nothing in the index depends on (CG-28). A query that NAMED one of
3613
+ // those types is asking about the declaration, so its file is exempt and
3614
+ // ranks at full weight.
3615
+ const isAmbientDeclaration = cg.ambientDeclarationFilePredicate(penaltyCandidates);
3616
+ const isDampedDeclaration = (filePath) => isAmbientDeclaration(filePath) && !namedTypeFiles.has(filePath);
3617
+ /**
3618
+ * Rank penalty for a file, applied to its relevance score AND (below) to its
3619
+ * graph mass — the two signals the sort actually keys on. Applying it to the
3620
+ * score alone would leave the #1500 case unfixed: the generated CRUD carries
3621
+ * MORE graph mass than the hand-written use-case, and graph mass outranks
3622
+ * score in the comparator.
3623
+ *
3624
+ * Generated and ambient-declaration are taken as the STRONGER of the two,
3625
+ * never multiplied: a generated `.d.ts` has one property — "not the
3626
+ * implementation" — that both signals happen to see, and charging it twice is
3627
+ * how a file gets cliffed out of answers where it is genuinely relevant
3628
+ * (CG-28). The low-value multiplier is orthogonal (a test file that is also
3629
+ * generated is two independent reasons) and still compounds.
3630
+ */
3631
+ const rankPenalty = (filePath) => Math.min(isGeneratedCandidate(filePath) ? GENERATED_RANK_PENALTY : 1, isDampedDeclaration(filePath) ? AMBIENT_DECLARATION_RANK_PENALTY : 1)
3632
+ * (isLowValue(filePath) ? LOW_VALUE_RANK_PENALTY : 1);
3633
+ for (const [filePath, group] of fileGroups) {
3634
+ group.score = (group.score + Math.min(PERIPHERAL_SCORE_CAP, group.peripheral))
3635
+ * rankPenalty(filePath);
3636
+ }
3637
+ // Hard-exclude test/spec files (ALL tiers — the per-tier `excludeLowValueFiles`
3638
+ // flag this used to be gated on was dead config and is gone). One slipped test
2737
3639
  // file dominates the per-file budget on small repos (cobra's `command_test.go`
2738
3640
  // displaced `args.go`) AND wastes budget on large ones (Django's
2739
3641
  // `custom_lookups/tests.py` ate ~2.3 KB of the 28 KB cap, crowding out the
@@ -2741,15 +3643,49 @@ class ToolHandler {
2741
3643
  // an architecture question. Skip when the query itself is about tests — the
2742
3644
  // legitimate "explore the tests" case — and only cut if ≥2 non-test candidates
2743
3645
  // remain (else tests are the only signal for this area).
3646
+ //
3647
+ // Runs BEFORE the score floor, on the whole gather. Judging "are there other
3648
+ // candidates?" on the post-floor set was too late: express's routing question
3649
+ // left one non-test file past the floor, the guard stood down, and the floor's
3650
+ // keep-minimum then pulled two test files back in as the "spread".
3651
+ let candidateFiles = [...fileGroups.entries()];
2744
3652
  {
2745
- const queryMentionsTests = /\b(test|tests|testing|spec|verify|verifies)\b/i.test(query);
3653
+ const queryMentionsTests = /\b(test|tests|testing|spec|verify|verifies)\b/i.test(matchQuery);
2746
3654
  if (!queryMentionsTests) {
2747
- const nonLow = relevantFiles.filter(([p]) => !isLowValue(p));
3655
+ // A pinned file is exempt: naming a test file by path IS asking for it.
3656
+ const nonLow = candidateFiles.filter(([p]) => !isLowValue(p) || pinnedSet.has(p));
2748
3657
  if (nonLow.length >= 2) {
2749
- relevantFiles = nonLow;
3658
+ candidateFiles = nonLow;
2750
3659
  }
2751
3660
  }
2752
- }
3661
+ diag?.setLowValueFiltered(fileGroups.size, candidateFiles.length);
3662
+ }
3663
+ // Relative score floor — see SCORE_FLOOR_* for why it is a fraction of the
3664
+ // best file's score and why that fraction is clamped at both ends.
3665
+ const topScore = Math.max(0, ...candidateFiles.map(([, g]) => g.score));
3666
+ const scoreFloor = Math.max(SCORE_FLOOR_ABSOLUTE, Math.min(SCORE_FLOOR_MAX, topScore * SCORE_FLOOR_FRACTION_OF_TOP));
3667
+ let relevantFiles = candidateFiles.filter(([fp, group]) => group.score >= scoreFloor || pinnedSet.has(fp));
3668
+ if (relevantFiles.length < SCORE_FLOOR_KEEP_MIN) {
3669
+ // Backfill from what the RELATIVE floor cut, best first, at two strengths:
3670
+ //
3671
+ // - THIN (1-2 files survived): only files with real evidence. A file whose
3672
+ // entire claim is one isolated variable scores 0.8 and stays out —
3673
+ // express's `examples/route-middleware` matched nothing but a local
3674
+ // `app` and would otherwise have taken 48% of that envelope. Padding a
3675
+ // precise answer with a wrong file doesn't save the agent the follow-up
3676
+ // call it would pad against.
3677
+ // - EMPTY (nothing survived): take the best of whatever matched. Returning
3678
+ // "no relevant code found" when the gather DID find candidates is the
3679
+ // worst outcome on the board — the agent falls straight back to grep.
3680
+ const minEvidence = relevantFiles.length === 0 ? Number.EPSILON : SCORE_FLOOR_ABSOLUTE;
3681
+ relevantFiles = candidateFiles
3682
+ .filter(([fp, group]) => group.score >= minEvidence || pinnedSet.has(fp))
3683
+ .sort((a, b) => (pinnedSet.has(b[0]) ? 1 : 0) - (pinnedSet.has(a[0]) ? 1 : 0)
3684
+ || b[1].score - a[1].score
3685
+ || b[1].nodes.length - a[1].nodes.length)
3686
+ .slice(0, Math.max(SCORE_FLOOR_KEEP_MIN, relevantFiles.length));
3687
+ }
3688
+ diag?.setScoreFloor(scoreFloor, relevantFiles.length);
2753
3689
  // Secondary signal: how many DISTINCT query terms each file matches (path +
2754
3690
  // symbol names). Kept only as a tiebreak — the PRIMARY relevance is graph
2755
3691
  // connectivity below. (Term counting alone tied the real central file with
@@ -2771,10 +3707,17 @@ class ToolHandler {
2771
3707
  // text match (LensSwitcher.swift, matched "switch" but calls nothing in the
2772
3708
  // flow) gets only its restart probability → ~0, and is dropped by the gate.
2773
3709
  const nodeRwr = this.computeGraphRelevance([...subgraph.nodes.keys()], subgraph.edges, entryNodeIds);
3710
+ //
3711
+ // Carries `rankPenalty` too, so generated/low-value files are demoted on the
3712
+ // sort's PRIMARY key rather than only at the tiebreak. Everything downstream
3713
+ // (centrality, the relevance gate, the buried-rescue test, the comparator)
3714
+ // reads this map, so the penalty applies once and applies everywhere.
2774
3715
  const fileGraphScore = new Map();
2775
3716
  for (const node of subgraph.nodes.values()) {
2776
3717
  fileGraphScore.set(node.filePath, (fileGraphScore.get(node.filePath) ?? 0) + (nodeRwr.get(node.id) ?? 0));
2777
3718
  }
3719
+ for (const [fp, mass] of fileGraphScore)
3720
+ fileGraphScore.set(fp, mass * rankPenalty(fp));
2778
3721
  const maxGraph = Math.max(0, ...fileGraphScore.values());
2779
3722
  // Central file(s): the 1-2 most graph-central files that also match the
2780
3723
  // query textually (so a connected hub-utility with no term match isn't
@@ -2819,7 +3762,7 @@ class ToolHandler {
2819
3762
  subgraph.nodes.set(t.id, t);
2820
3763
  let group = fileGroups.get(fp);
2821
3764
  if (!group) {
2822
- group = { nodes: [], score: 0 };
3765
+ group = { nodes: [], score: 0, peripheral: 0 };
2823
3766
  fileGroups.set(fp, group);
2824
3767
  }
2825
3768
  if (!group.nodes.some((n) => n.id === t.id))
@@ -2841,13 +3784,18 @@ class ToolHandler {
2841
3784
  // dropped, so the budget never fills with incidental files. Guarded so it
2842
3785
  // never prunes below 2.
2843
3786
  if (maxGraph > 0) {
2844
- const gated = relevantFiles.filter(([fp]) => (fileGraphScore.get(fp) ?? 0) >= maxGraph * 0.06
3787
+ const gated = relevantFiles.filter(([fp]) => pinnedSet.has(fp)
3788
+ || (fileGraphScore.get(fp) ?? 0) >= maxGraph * 0.06
2845
3789
  || centralFiles.has(fp)
2846
3790
  || entryFiles.has(fp)
2847
3791
  || changeSurfaceFiles.has(fp)
2848
3792
  || (fileTermHits.get(fp) ?? 0) >= 2);
2849
3793
  if (gated.length >= 2)
2850
3794
  relevantFiles = gated;
3795
+ diag?.setRelevanceGate(maxGraph, maxGraph * 0.06, gated.length >= 2, relevantFiles.length);
3796
+ }
3797
+ else {
3798
+ diag?.setRelevanceGate(maxGraph, 0, false, relevantFiles.length);
2851
3799
  }
2852
3800
  // Sort files: graph-central first, then distinct-term match, then the
2853
3801
  // existing low-value/generated/score tiebreaks.
@@ -2891,7 +3839,16 @@ class ToolHandler {
2891
3839
  const sortedFiles = relevantFiles.sort((a, b) => {
2892
3840
  const aPath = a[0].toLowerCase();
2893
3841
  const bPath = b[0].toLowerCase();
2894
- // Agent-named files first (it asked for a symbol defined here by name).
3842
+ // Pinned files first of all — the agent named the FILE by path, which is
3843
+ // even more explicit than naming a symbol in it. Among pins, keep the
3844
+ // order they appeared in the query.
3845
+ const aPin = pinnedSet.has(a[0]) ? 1 : 0;
3846
+ const bPin = pinnedSet.has(b[0]) ? 1 : 0;
3847
+ if (aPin !== bPin)
3848
+ return bPin - aPin;
3849
+ if (aPin && bPin)
3850
+ return (pinnedOrder.get(a[0]) ?? 0) - (pinnedOrder.get(b[0]) ?? 0);
3851
+ // Agent-named files next (it asked for a symbol defined here by name).
2895
3852
  const aNamed = namedSeedFiles.has(a[0]) ? 1 : 0;
2896
3853
  const bNamed = namedSeedFiles.has(b[0]) ? 1 : 0;
2897
3854
  if (aNamed !== bNamed)
@@ -2920,9 +3877,13 @@ class ToolHandler {
2920
3877
  // when asking about the actual flow, and dumping their bodies inflates
2921
3878
  // the response (the cosmos Q3 explore otherwise leads with
2922
3879
  // `expected_keepers_mocks.go`, displacing the real `tally.go` content
2923
- // and forcing the agent to Read tally.go anyway).
2924
- const aGen = (0, generated_detection_1.isGeneratedFile)(a[0]);
2925
- const bGen = (0, generated_detection_1.isGeneratedFile)(b[0]);
3880
+ // and forcing the agent to Read tally.go anyway). Both this and the
3881
+ // low-value key above are now BACKSTOPS: `rankPenalty` has already scaled
3882
+ // the score and the graph mass these files reach this comparison with, so
3883
+ // a generated file no longer outranks a hand-written one just by scoring
3884
+ // higher (#1500). This still settles the exact ties the penalty leaves.
3885
+ const aGen = isGeneratedCandidate(a[0]);
3886
+ const bGen = isGeneratedCandidate(b[0]);
2926
3887
  if (aGen !== bGen)
2927
3888
  return aGen ? 1 : -1;
2928
3889
  if (a[1].score !== b[1].score)
@@ -2983,7 +3944,58 @@ class ToolHandler {
2983
3944
  // Compute the flow spine once — used both to prepend the Flow section (below)
2984
3945
  // and to gate adaptive source sizing: files on the spine get full source,
2985
3946
  // off-spine peers skeletonize.
2986
- const flow = this.buildFlowFromNamedSymbols(cg, query);
3947
+ const flow = this.buildFlowFromNamedSymbols(cg, matchQuery);
3948
+ // Snapshot every ranked candidate's scoring inputs, in final sort order, so
3949
+ // the diagnostic can show what each file's share of the envelope was BOUGHT
3950
+ // with (score, graph mass, term hits, flags) — not just what it cost.
3951
+ if (diag) {
3952
+ const kindMix = (nodes) => {
3953
+ const counts = new Map();
3954
+ for (const n of nodes)
3955
+ counts.set(n.kind, (counts.get(n.kind) ?? 0) + 1);
3956
+ return [...counts.entries()]
3957
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
3958
+ .map(([k, c]) => `${k}:${c}`)
3959
+ .join(' ');
3960
+ };
3961
+ sortedFiles.forEach(([fp, group], i) => {
3962
+ diag.noteCandidate(fp, {
3963
+ rank: i + 1,
3964
+ score: group.score,
3965
+ graphScore: fileGraphScore.get(fp) ?? 0,
3966
+ termHits: fileTermHits.get(fp) ?? 0,
3967
+ nodes: group.nodes.length,
3968
+ pinned: pinnedSet.has(fp),
3969
+ named: namedSeedFiles.has(fp),
3970
+ central: centralFiles.has(fp),
3971
+ entry: entryFiles.has(fp),
3972
+ spine: group.nodes.some((n) => flow.pathNodeIds.has(n.id)),
3973
+ lowValue: isLowValue(fp),
3974
+ generated: isGeneratedCandidate(fp),
3975
+ ambientDeclaration: isAmbientDeclaration(fp),
3976
+ penalty: rankPenalty(fp),
3977
+ kinds: kindMix(group.nodes),
3978
+ });
3979
+ });
3980
+ }
3981
+ // Score-proportional byte allocation (CG-12). Every file's share of the
3982
+ // envelope is reserved HERE, before a single byte renders, so the render loop
3983
+ // spends a reservation instead of racing for whatever the files above it left.
3984
+ const allocation = allocateExploreBudget(sortedFiles.map(([fp, group]) => ({
3985
+ path: fp,
3986
+ score: group.score,
3987
+ // A pinned file's bytes are worth full price by definition — the agent
3988
+ // asked for the file itself, generated/test or not.
3989
+ worth: pinnedSet.has(fp) ? 1 : rankPenalty(fp),
3990
+ spine: group.nodes.some((n) => flow.pathNodeIds.has(n.id)),
3991
+ pinned: pinnedSet.has(fp),
3992
+ })), budget, maxFiles);
3993
+ diag?.setAllocation(allocation.allowances, allocation.cliffed, allocation.cliffAt, allocation.pool);
3994
+ // Cliffed files ship as pointers — path, symbols, line numbers — so the agent
3995
+ // can name one in a follow-up explore. Rendered below with the other
3996
+ // not-shown files, and force-enabled even on tiers that suppress that list:
3997
+ // a file we deliberately withheld source for must still be nameable.
3998
+ const cliffedFiles = new Set(allocation.cliffed);
2987
3999
  // Polymorphic-sibling detector for adaptive sizing. A class that implements/
2988
4000
  // extends a supertype shared by >= MIN_SIBLINGS classes is one of many
2989
4001
  // INTERCHANGEABLE implementations (OkHttp's 14 `: Interceptor` classes —
@@ -3024,7 +4036,7 @@ class ToolHandler {
3024
4036
  const superMany = new Map();
3025
4037
  const definesPolymorphicSupertype = (nodes) => {
3026
4038
  for (const n of nodes) {
3027
- if (n.kind !== 'class' && n.kind !== 'interface' && n.kind !== 'struct'
4039
+ if (n.kind !== 'class' && n.kind !== 'interface' && n.kind !== 'struct' && n.kind !== 'union'
3028
4040
  && n.kind !== 'trait' && n.kind !== 'protocol' && n.kind !== 'type_alias')
3029
4041
  continue;
3030
4042
  let many = superMany.get(n.id);
@@ -3040,38 +4052,362 @@ class ToolHandler {
3040
4052
  };
3041
4053
  lines.push('**Source Code**');
3042
4054
  lines.push('');
4055
+ // Recorded so the drift pass below (#1474) can append a per-file exception
4056
+ // to this guarantee after the render loop knows which files drifted.
4057
+ const verbatimHeaderIdx = lines.length;
3043
4058
  lines.push('> The code below is the **verbatim, current on-disk source** of these files — re-read from disk on this call and line-numbered, byte-for-byte identical to what the Read tool returns. It is NOT a summary, outline, or stale cache. Treat each block as a Read you have already performed: do not Read a file shown here.');
3044
4059
  lines.push('');
3045
- let totalChars = lines.join('\n').length;
4060
+ // The response's absolute cap. It MUST stay under the host's inline
4061
+ // tool-result limit (~25K chars): above it the result is externalized to a
4062
+ // file the agent Reads back (a 35K vscode explore did exactly this in the
4063
+ // n=4 A/B).
4064
+ const hardCeiling = Math.min(Math.round(budget.maxOutputChars * 1.5), 25000);
4065
+ // What the epilogue is OWED — the part of it the loop must not spend (CG-26).
4066
+ // Not a flat margin: the old 600 was neither the epilogue's size (1,064 on
4067
+ // gin, 2,231 on excalidraw) nor a bound on it, so the loop budgeted for a
4068
+ // thing that did not exist and the response then discarded the whole
4069
+ // epilogue to fit. The floor is what the epilogue owes the AGENT rather
4070
+ // than what it costs us:
4071
+ // - the one-line note that says an uncovered area exists (always), and
4072
+ // - a pointer for every file whose source was deliberately WITHHELD.
4073
+ // A cliffed file's bytes were traded away on the promise that the agent
4074
+ // can still name it in a follow-up call (CG-12); if the ceiling then
4075
+ // eats that name the trade was a silent drop.
4076
+ // Everything above the floor — the rest of the pointer list, the reminders
4077
+ // — is elastic and fitted to the room that is actually left, at the end of
4078
+ // this method. Sized from the REAL strings, never tuned: a constant swept
4079
+ // against the suite is what CG-30's record warns about.
4080
+ const cliffPointerFloor = [...cliffedFiles]
4081
+ .slice(0, POINTER_MAX_FILES)
4082
+ .reduce((n, fp) => {
4083
+ const g = fileGroups.get(fp);
4084
+ return g ? n + pointerLineFor(fp, g.nodes).length + 1 : n;
4085
+ }, cliffedFiles.size > 0 ? POINTER_HEADER.length + 2 : 0);
4086
+ const epilogueFloor = EPILOGUE_LOST_NOTE.length + 2 + cliffPointerFloor;
4087
+ // Absolute stop for the render loop. Reservations already fit the envelope, so
4088
+ // this only catches their bounded overshoot (the whole-file grace, an oversize
4089
+ // first cluster) — and catches it HERE, where a file can be skipped cleanly and
4090
+ // a later one still render, instead of at the final truncation, which lops off
4091
+ // whichever section happened to land last.
4092
+ const renderCeiling = hardCeiling - epilogueFloor;
4093
+ // `flow.text` is PART of the response — it is prepended to `lines` to make
4094
+ // the final output — so the render loop has to spend against it, and it
4095
+ // never did. Counting it is what makes `renderCeiling` the ceiling it
4096
+ // claims to be: without it the loop believed it had room for a trailing
4097
+ // section the final truncation then threw away whole, and (CG-31) the
4098
+ // displacement guard dutifully held bytes back to pay for that section —
4099
+ // taking them off a file the agent DOES receive and handing them to one it
4100
+ // never sees.
4101
+ let totalChars = flow.text.length + lines.join('\n').length;
3046
4102
  let filesIncluded = 0;
3047
4103
  // Paths we actually render source for below. Drives the curated header count
3048
4104
  // (#1046) — it must reflect what we show, not the raw candidate gather.
3049
4105
  const renderedFilePaths = [];
3050
4106
  let anyFileTrimmed = false;
3051
- for (const [filePath, group] of sortedFiles) {
3052
- if (filesIncluded >= maxFiles)
4107
+ // Files that changed on disk after their last index sync (#1474). Their
4108
+ // indexed line ranges are untrustworthy, so sliced renders (adaptive /
4109
+ // skeleton / clusters) are OFF for them: a small drifted file still ships
4110
+ // whole (current bytes, correct by construction → staleRendered), a big one
4111
+ // is omitted with an explicit notice (→ staleOmitted) — honest absence
4112
+ // instead of a different symbol's code under the requested name.
4113
+ const staleRendered = [];
4114
+ const staleOmitted = [];
4115
+ let suppressedFallback = null;
4116
+ // Reservation carry-forward (CG-21). A reservation is a promise the render
4117
+ // loop has to KEEP, not a cap it may quietly under-use: a file that cannot
4118
+ // spend what it was given — thin matched-symbol set, unreadable, drifted off
4119
+ // disk, skipped for the ceiling — must hand the difference DOWN the rank
4120
+ // order, not drop it. Tracked as two running totals rather than a `spent`
4121
+ // variable threaded through the dozen `continue`s below, so no exit path can
4122
+ // forget to account: everything the loop has PROMISED so far, and everything
4123
+ // it has actually EMITTED. Their gap is the slack the next file may add to
4124
+ // its own reservation.
4125
+ //
4126
+ // Symmetric on the other side: a whole-file buy that overshoots makes
4127
+ // `sourceSpent` outrun `reservedSoFar`, which suppresses slack until a later
4128
+ // under-spend covers the debt. So the pool is conserved in both directions,
4129
+ // and no file is ever cut BELOW the reservation it was promised.
4130
+ let reservedSoFar = 0;
4131
+ let sourceSpent = 0;
4132
+ // Funding line for the whole-file BUY rule: the response's SOURCE may reach
4133
+ // everything the allocator promised plus one bounded overshoot, and no more.
4134
+ // Measured against the promise rather than `renderCeiling` on purpose — the
4135
+ // ceiling sits 50% above the envelope and says nothing about who is owed
4136
+ // what, so funding a buy from it just moves the shortfall to whichever file
4137
+ // the loop reaches last. See WHOLE_FILE_BUY_OVERSHOOT_FRACTION.
4138
+ const reservedTotal = [...allocation.allowances.values()].reduce((sum, n) => sum + n, 0);
4139
+ const sourceCeiling = reservedTotal + Math.round(budget.maxOutputChars * exports.EXPLORE_ALLOCATION.WHOLE_FILE_BUY_OVERSHOOT_FRACTION);
4140
+ /**
4141
+ * What a file's section costs BESIDES its source, in render space: the
4142
+ * header (path + up to `maxSymbolsInFileHeader` symbol names) plus the code
4143
+ * fence and the blank lines around them (CG-26).
4144
+ *
4145
+ * `EXPLORE_ALLOCATION.FILE_OVERHEAD` is the ALLOCATOR's constant — the flat
4146
+ * 200 it charges each admitted file when it splits the envelope — and using
4147
+ * it here too was a category error worth ~250 chars per pending file: the
4148
+ * render loop then held back a file's reservation but not the header that
4149
+ * reservation has to arrive under, so the last admitted file was left just
4150
+ * short of the room it needed and skipped whole. Estimated from the file's
4151
+ * own candidate symbols, which is what the header is actually built from.
4152
+ */
4153
+ const overheadCache = new Map();
4154
+ const sectionOverhead = (filePath, nodes) => {
4155
+ const hit = overheadCache.get(filePath);
4156
+ if (hit !== undefined)
4157
+ return hit;
4158
+ const names = [...new Set(nodes.filter((n) => n.kind !== 'import' && n.kind !== 'export')
4159
+ .map((n) => `${n.name}(${n.kind})`))].slice(0, budget.maxSymbolsInFileHeader);
4160
+ // header + blank, then ```lang / body / ``` / blank around the source.
4161
+ const cost = fileSectionHeader(filePath, names.join(', ')).length + 2
4162
+ + (nodes[0]?.language?.length ?? 0) + 11;
4163
+ overheadCache.set(filePath, cost);
4164
+ return cost;
4165
+ };
4166
+ /**
4167
+ * How much of what is still owed BELOW `fileIndex` the response can actually
4168
+ * still PAY, in render-space chars (CG-31).
4169
+ *
4170
+ * Not the same as the sum of those reservations. The allocator splits the
4171
+ * envelope; the render loop spends against a ceiling that also has to hold
4172
+ * the response's own prose, so on a saturated response the promises are
4173
+ * OVER-SUBSCRIBED and the tail is going to be dropped whatever happens
4174
+ * above it. Bytes held back for a file that then gets dropped are bytes
4175
+ * nobody ever receives — measured on django, holding the full owed sum cost
4176
+ * the rank-#1 file 2,126 chars and handed them to a rank-#6 section the
4177
+ * hard ceiling threw away. So walk the remaining files in RANK order and
4178
+ * hold back only the prefix that fits `budgetLeft`; the first one that does
4179
+ * not fit ends it, because everything after it is further out of reach.
4180
+ *
4181
+ * Conservative and self-correcting: it assumes each file below spends its
4182
+ * whole reservation, and when they do not, the carry-forward hands the
4183
+ * difference to whoever comes next anyway.
4184
+ */
4185
+ const owedPayableBelow = (fileIndex, budgetLeft) => {
4186
+ let held = 0;
4187
+ for (let j = fileIndex + 1; j < sortedFiles.length; j++) {
4188
+ const path = sortedFiles[j][0];
4189
+ const r = allocation.allowances.get(path);
4190
+ if (r === undefined)
4191
+ continue;
4192
+ const overhead = sectionOverhead(path, sortedFiles[j][1].nodes);
4193
+ const need = r + overhead;
4194
+ if (held + need > budgetLeft) {
4195
+ // PART of a reservation is still a delivered file (CG-26). Holding
4196
+ // all-or-nothing zeroed the last admitted file whenever its full
4197
+ // reservation no longer fit: on the precise-query fixture the rank-5
4198
+ // file took 4,134 chars against a 2,948 reservation while rank 6 —
4199
+ // admitted, reserved 2,539 — was left 4 chars and skipped. Hold the
4200
+ // remainder instead, but only while it is still worth a section:
4201
+ // under MIN_CHARS a slice cannot hold one complete method, and a
4202
+ // fragment forces the Read this tool exists to prevent.
4203
+ const partial = budgetLeft - held;
4204
+ if (partial >= exports.EXPLORE_ALLOCATION.MIN_CHARS + overhead)
4205
+ held += partial;
4206
+ break;
4207
+ }
4208
+ held += need;
4209
+ }
4210
+ return held;
4211
+ };
4212
+ for (let fileIndex = 0; fileIndex < sortedFiles.length; fileIndex++) {
4213
+ const [filePath, group] = sortedFiles[fileIndex];
4214
+ if (filesIncluded >= maxFiles) {
4215
+ if (diag)
4216
+ for (const [fp] of sortedFiles)
4217
+ diag.recordSkip(fp, 'max-files');
3053
4218
  break;
3054
- // A file DEFINES a named/spine symbol (the answer) vs merely references the
3055
- // flow. Past 90% budget, stop pulling INCIDENTAL files — but keep scanning
3056
- // for necessary ones, which render even past the cap (bounded by maxFiles).
3057
- // Without this `continue` (was an unconditional `break`), the loop stopped
3058
- // after the build + validators-exec files and never reached the ranked-in
3059
- // validate-logic file (Alamofire's Validation.swift).
3060
- const fileNecessary = group.nodes.some(n => entryNodeIds.has(n.id) || flow.pathNodeIds.has(n.id) || flow.uniqueNamedNodeIds.has(n.id));
3061
- if (!fileNecessary && totalChars > budget.maxOutputChars * 0.9)
4219
+ }
4220
+ // Below the relevance cliff: no source, no `maxFiles` slot. It is still
4221
+ // named — with its matched symbols and their line numbers — in the
4222
+ // not-shown list, so one follow-up explore fetches it in full.
4223
+ if (cliffedFiles.has(filePath)) {
4224
+ diag?.recordSkip(filePath, 'cliff');
4225
+ continue;
4226
+ }
4227
+ // This file's reserved share of the envelope. Every render path below is
4228
+ // bounded by it instead of by the flat per-file cap, which is what stops
4229
+ // allocation from following file size: a small weakly-relevant file no
4230
+ // longer ships whole while the strongly-relevant one is clipped.
4231
+ const reserved = allocation.allowances.get(filePath);
4232
+ if (reserved === undefined) {
4233
+ diag?.recordSkip(filePath, 'max-files');
3062
4234
  continue;
4235
+ }
4236
+ // What this file may actually spend: its own reservation PLUS whatever the
4237
+ // files above it left on the table. Every render bound below reads this,
4238
+ // never `reserved` — that is what makes the carry-forward reach the render
4239
+ // paths instead of being bookkeeping. Slack flows to the next file in RANK
4240
+ // order because that is the only file a single-pass loop can still pay;
4241
+ // `MAX_SHARE` keeps that from turning a weak tail file into the response,
4242
+ // so the allocator's share ceiling holds end-to-end and not just at
4243
+ // reservation time.
4244
+ const allowance = Math.min(reserved + Math.max(0, reservedSoFar - sourceSpent), Math.max(reserved, Math.round(budget.maxOutputChars * exports.EXPLORE_ALLOCATION.MAX_SHARE)));
4245
+ reservedSoFar += reserved;
4246
+ diag?.recordSpendable(filePath, allowance);
4247
+ // DISPLACEMENT GUARD, in render space (CG-31). `allowance` says what this
4248
+ // file MAY spend; it does not say the bytes are still there to spend. The
4249
+ // hard ceiling is shared with every file the loop has not reached yet, and
4250
+ // their reservations are promises the allocator already made — so what is
4251
+ // left before the ceiling is not all ours. Holding that back is the same
4252
+ // inequality the whole-file BUY arm enforces with `owedBelow` (see below),
4253
+ // moved into the units the cluster path actually spends in: source PLUS
4254
+ // the per-section overhead each pending file will charge.
4255
+ //
4256
+ // Held back only where it can be PAID — see `owedPayableBelow`. A promise
4257
+ // the ceiling cannot reach is not a claim on this file's bytes; honouring
4258
+ // it anyway just moves source from a file the agent gets to one it does
4259
+ // not.
4260
+ //
4261
+ // Floored at this file's OWN reservation, never below: a kept promise is
4262
+ // not a displacement, and cutting a file under what it earned is the
4263
+ // failure this whole allocation layer exists to prevent.
4264
+ //
4265
+ // Slack still reaches the file: a file above that under-spends leaves
4266
+ // `totalChars` lower, which raises `headroom` one-for-one, so the
4267
+ // carry-forward the `allowance` line grants is exactly the carry-forward
4268
+ // this bound funds.
4269
+ const headroom = Math.max(0, renderCeiling - totalChars - sectionOverhead(filePath, group.nodes));
4270
+ const fundedHeadroom = Math.max(Math.min(reserved, headroom), headroom - owedPayableBelow(fileIndex, Math.max(0, headroom - reserved)));
4271
+ diag?.recordFunded(filePath, fundedHeadroom);
3063
4272
  const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, filePath);
3064
- if (!absPath || !(0, fs_1.existsSync)(absPath))
4273
+ if (!absPath || !(0, fs_1.existsSync)(absPath)) {
4274
+ diag?.recordSkip(filePath, 'unreadable');
3065
4275
  continue;
4276
+ }
3066
4277
  let fileContent;
3067
4278
  try {
3068
4279
  fileContent = (0, fs_1.readFileSync)(absPath, 'utf-8');
3069
4280
  }
3070
4281
  catch {
4282
+ diag?.recordSkip(filePath, 'unreadable');
3071
4283
  continue;
3072
4284
  }
3073
4285
  const fileLines = fileContent.split('\n');
3074
4286
  const lang = group.nodes[0]?.language || '';
4287
+ const withLineNumbers = exploreLineNumbersEnabled();
4288
+ // Language-neutral separator between two non-contiguous slices of one file
4289
+ // (no `//` — not a comment in Python, Ruby, etc.). With line numbers on,
4290
+ // the line-number jump also signals the gap.
4291
+ const GAP_MARKER = '\n\n... (gap) ...\n\n';
4292
+ // Cross-call dedup (CG-18). `served` is what THIS session already sent the
4293
+ // agent for THIS file, and it is empty unless the file still hashes to the
4294
+ // bytes those spans were sliced from — an edit between calls means the
4295
+ // agent's copy is wrong, so nothing is withheld. Every render path below
4296
+ // routes its spans through `dedupeSpans`, which is the only place a span
4297
+ // is ever dropped.
4298
+ const fingerprint = (0, explore_dedup_1.fileFingerprint)(fileContent);
4299
+ const served = dedupEnabled ? (0, explore_dedup_1.servedRangesForFile)(priorCalls, filePath, fingerprint) : [];
4300
+ /** Render one line span exactly as the render paths do. */
4301
+ const renderSpan = (r) => {
4302
+ const slice = fileLines.slice(r.start - 1, r.end).join('\n');
4303
+ return withLineNumbers ? numberSourceLines(slice, r.start) : slice;
4304
+ };
4305
+ /**
4306
+ * Apply the session history to a set of spans-with-text. A span the agent
4307
+ * already holds is dropped and reported in `covered`; a partially-held one
4308
+ * is re-rendered down to its new lines. Text is rebuilt from the surviving
4309
+ * spans rather than sliced out of the original string — the spans ARE the
4310
+ * contract with the session record, so rebuilding from them is what keeps
4311
+ * what we claim to have sent and what we sent the same thing.
4312
+ */
4313
+ const dedupeSpans = (parts) => {
4314
+ if (served.length === 0)
4315
+ return { parts: [...parts], covered: [] };
4316
+ const kept = [];
4317
+ const covered = [];
4318
+ for (const part of parts) {
4319
+ const split = (0, explore_dedup_1.dedupeRange)(part.range, served);
4320
+ if (split.covered.length === 0) {
4321
+ kept.push(part);
4322
+ continue;
4323
+ }
4324
+ covered.push(...split.covered);
4325
+ for (const r of split.emit)
4326
+ kept.push({ range: r, text: renderSpan(r) });
4327
+ }
4328
+ return { parts: kept, covered: (0, explore_dedup_1.mergeRanges)(covered) };
4329
+ };
4330
+ const coveredChars = (spans) => spans.reduce((sum, r) => sum + fileLines.slice(r.start - 1, r.end).join('\n').length, 0);
4331
+ /**
4332
+ * Emit one file's section — header, the back-reference for whatever the
4333
+ * agent already holds, and the fence for what is new. Every render path
4334
+ * ends here so that the dedup bookkeeping (freed bytes, freed `maxFiles`
4335
+ * slot, the session record, the diagnostic) is written in exactly one
4336
+ * place and no path can forget a piece of it.
4337
+ *
4338
+ * A fully-held file emits its header and pointer and NO fence, and
4339
+ * deliberately does not consume a `maxFiles` slot: that is half of where
4340
+ * the reclaimed budget goes (the other half is `sourceSpent`, which the
4341
+ * carry-forward pool hands down the rank order). Both send bytes to files
4342
+ * the agent has NOT seen, which is the whole point.
4343
+ */
4344
+ const emitFileSection = (opts) => {
4345
+ // A remainder too small to be worth a fence is folded into the pointer
4346
+ // (see MIN_DELTA_CHARS). Its ranges are then NOT recorded — the record
4347
+ // must only ever claim source that was actually sent.
4348
+ const folded = opts.covered.length > 0 && opts.body.length < explore_dedup_1.EXPLORE_DEDUP.MIN_DELTA_CHARS;
4349
+ const body = folded ? '' : opts.body;
4350
+ const ranges = folded ? [] : opts.ranges;
4351
+ const at = lines.length;
4352
+ lines.push(opts.header, '');
4353
+ // Charge what the section ACTUALLY costs, not a flat 200 (CG-26). A
4354
+ // header carries the path plus up to `maxSymbolsInFileHeader` symbol
4355
+ // names and routinely runs 300–500 chars, so the flat charge made the
4356
+ // loop believe it had room it did not have: okhttp rendered 26,601
4357
+ // chars against a 24,400 ceiling and the final truncation threw a
4358
+ // fully-rendered section away. Everything downstream is expressed in
4359
+ // these units — `headroom`, `fundedHeadroom`, every fit test — so an
4360
+ // under-count is not a rounding error, it funds a promise out of bytes
4361
+ // that do not exist and starves whoever the loop reaches last.
4362
+ totalChars += opts.header.length + 2;
4363
+ if (opts.covered.length > 0) {
4364
+ const pointer = (0, explore_dedup_1.formatBackReference)(filePath, opts.covered, (0, explore_dedup_1.symbolsInSpans)(group.nodes, opts.covered), { partial: body.length > 0 });
4365
+ lines.push(pointer, '');
4366
+ totalChars += pointer.length + 2;
4367
+ backReferencedFiles.push(filePath);
4368
+ }
4369
+ if (body.length > 0) {
4370
+ lines.push('```' + lang, body, '```', '');
4371
+ // ```lang \n body \n ``` \n '' \n — exact, same as the header above.
4372
+ totalChars += body.length + lang.length + 11;
4373
+ sourceSpent += body.length;
4374
+ newSourceChars += body.length;
4375
+ diag?.recordRender(filePath, opts.mode, body.length, opts.clipped || opts.covered.length > 0);
4376
+ if (opts.covered.length > 0)
4377
+ diag?.recordDedup(filePath, coveredChars(opts.covered), opts.covered);
4378
+ noteEmitted(filePath, [...ranges, ...opts.covered], body.length, fingerprint);
4379
+ renderedFilePaths.push(filePath);
4380
+ filesIncluded++;
4381
+ return;
4382
+ }
4383
+ // Fully held. The section is the pointer; the slot and the bytes go to a
4384
+ // file the agent has not seen. The spans are still recorded (at zero
4385
+ // bytes) because the record means "source the agent HAS", not "bytes
4386
+ // this call spent" — refreshing them keeps a long session from ageing
4387
+ // them out of the retained window and re-serving them for nothing.
4388
+ // (The header is already charged above; a fully-held section is the
4389
+ // header plus the pointer and nothing else.)
4390
+ diag?.recordRender(filePath, 'backref', 0, false);
4391
+ diag?.recordDedup(filePath, coveredChars(opts.covered), opts.covered);
4392
+ noteEmitted(filePath, opts.covered, 0, fingerprint);
4393
+ renderedFilePaths.push(filePath);
4394
+ if (!suppressedFallback && opts.fullBody.length > 0) {
4395
+ suppressedFallback = {
4396
+ filePath,
4397
+ at,
4398
+ replacing: lines.length - at,
4399
+ section: [opts.header, '', '```' + lang, opts.fullBody, '```', ''],
4400
+ sourceChars: opts.fullBody.length,
4401
+ overhead: opts.overhead,
4402
+ ranges: opts.fullRanges,
4403
+ fingerprint,
4404
+ };
4405
+ }
4406
+ };
4407
+ // Disk-drift gate (#1474): every render branch below except whole-file
4408
+ // slices fileContent (CURRENT bytes) at INDEXED line ranges. Content is
4409
+ // already in hand, so the check costs one stat (hash only on mismatch).
4410
+ const fileStale = this.isFileStaleOnDisk(cg, filePath, fileContent);
3075
4411
  // Adaptive sizing (CODEGRAPH_ADAPTIVE_EXPLORE, default on): collapse a file
3076
4412
  // to a per-symbol view when it's a redundant member of a polymorphic family.
3077
4413
  // Engages iff ALL hold:
@@ -3108,9 +4444,9 @@ class ToolHandler {
3108
4444
  .filter(n => CALLABLE_BODY.has(n.kind) && (flow.pathNodeIds.has(n.id) || flow.uniqueNamedNodeIds.has(n.id)))
3109
4445
  .reduce((s, n) => s + fileLines.slice(n.startLine - 1, n.endLine).join('\n').length, 0);
3110
4446
  const onSpineGodFile = hasSpineNode
3111
- && namedBodyChars > budget.maxCharsPerFile
4447
+ && namedBodyChars > allowance
3112
4448
  && group.nodes.some(n => CALLABLE_BODY.has(n.kind) && flow.uniqueNamedNodeIds.has(n.id) && !flow.pathNodeIds.has(n.id));
3113
- if (adaptiveExploreEnabled() && flow.pathNodeIds.size > 0
4449
+ if (!fileStale && adaptiveExploreEnabled() && flow.pathNodeIds.size > 0
3114
4450
  && (onSpineGodFile || (!hasSpineNode && isPolymorphicSibling(group.nodes) && !spared))) {
3115
4451
  const syms = group.nodes
3116
4452
  .filter(n => n.kind !== 'import' && n.kind !== 'export' && n.startLine > 0)
@@ -3126,14 +4462,20 @@ class ToolHandler {
3126
4462
  : flow.pathNodeIds.has(n.id) ? 0
3127
4463
  : flow.uniqueNamedNodeIds.has(n.id) ? 1
3128
4464
  : (fileDefinesSuper && flow.namedNodeIds.has(n.id)) ? 2 : 99;
3129
- // One ~250-line WINDOW per file. syms are taken by priority (spine first,
3130
- // then uniquely-named, then family-base), and the cap applies to ALL of
3131
- // them — including the spine — so a big-spine god-file (tokio's worker.rs:
3132
- // run→run_task→next_task→steal_work) can't eat the whole response and
3133
- // starve the co-flow file (harness.rs's poll). The native agent windows
3134
- // such a file too (~190 lines at a time), so this mimics, not truncates.
3135
- // Always emit ≥1 (never an empty section).
3136
- const bodyCap = budget.maxCharsPerFile * 1.5;
4465
+ // One WINDOW per file, sized by this file's RESERVATION. syms are taken by
4466
+ // priority (spine first, then uniquely-named, then family-base), and the cap
4467
+ // applies to ALL of them — including the spine — so a big-spine god-file
4468
+ // (tokio's worker.rs: run→run_task→next_task→steal_work) can't eat the whole
4469
+ // response and starve the co-flow file (harness.rs's poll). The native agent
4470
+ // windows such a file too (~190 lines at a time), so this mimics, not
4471
+ // truncates. Always emit ≥1 (never an empty section).
4472
+ //
4473
+ // Held to `fundedHeadroom` as well (CG-31) so this path cannot spend a
4474
+ // reservation still owed below it either. It never exceeds `allowance`
4475
+ // today, so the bound only bites once the ceiling is genuinely tight —
4476
+ // but "every render path" has to mean every one, or the guard is just a
4477
+ // detour the next god-file takes.
4478
+ const bodyCap = Math.min(allowance, fundedHeadroom);
3137
4479
  const bodyIds = new Set();
3138
4480
  let bodyChars = 0;
3139
4481
  for (const n of syms.filter(n => prio(n) < 99 && n.endLine >= n.startLine).sort((a, b) => prio(a) - prio(b))) {
@@ -3156,7 +4498,10 @@ class ToolHandler {
3156
4498
  if (bodyIds.has(n.id)) {
3157
4499
  const end = n.endLine;
3158
4500
  const body = fileLines.slice(n.startLine - 1, end).join('\n');
3159
- skel.push(exploreLineNumbersEnabled() ? numberSourceLines(body, n.startLine) : body);
4501
+ skel.push({
4502
+ range: { start: n.startLine, end },
4503
+ text: withLineNumbers ? numberSourceLines(body, n.startLine) : body,
4504
+ });
3160
4505
  coveredUntil = end;
3161
4506
  }
3162
4507
  else {
@@ -3177,13 +4522,15 @@ class ToolHandler {
3177
4522
  }
3178
4523
  const sig = (fileLines[lineNo - 1] || '').trim();
3179
4524
  if (sig) {
3180
- skel.push(exploreLineNumbersEnabled() ? `${lineNo}\t${sig}` : sig);
4525
+ skel.push({
4526
+ range: { start: lineNo, end: lineNo },
4527
+ text: withLineNumbers ? `${lineNo}\t${sig}` : sig,
4528
+ });
3181
4529
  sigCount++;
3182
4530
  }
3183
4531
  }
3184
4532
  }
3185
- if (sigDropped > 0)
3186
- skel.push(`… +${sigDropped} more (signatures elided)`);
4533
+ const sigTail = sigDropped > 0 ? `… +${sigDropped} more (signatures elided)` : '';
3187
4534
  if (skel.length > 0) {
3188
4535
  const names = [...new Set(group.nodes.filter(n => n.kind !== 'import' && n.kind !== 'export').map(n => n.name))]
3189
4536
  .slice(0, budget.maxSymbolsInFileHeader).join(', ');
@@ -3196,10 +4543,24 @@ class ToolHandler {
3196
4543
  const tag = bodyIds.size > 0
3197
4544
  ? 'focused (the methods you named in full, the rest as signatures — codegraph_explore a signature by name for its body; do NOT Read)'
3198
4545
  : 'skeleton (signatures only — codegraph_explore a name for its full body; do NOT Read)';
3199
- lines.push(fileSectionHeader(filePath, `${names} · ${tag}`), '', '```' + lang, skel.join('\n'), '```', '');
3200
- totalChars += skel.join('\n').length + 120;
3201
- renderedFilePaths.push(filePath);
3202
- filesIncluded++;
4546
+ // Dedup runs on the per-symbol parts, so a body the agent already has
4547
+ // becomes a pointer while the signature map around it survives intact
4548
+ // (a one-line signature is far under MIN_COVERED_LINES and is never
4549
+ // withheld — the structure map is what makes this render legible).
4550
+ const dd = dedupeSpans(skel);
4551
+ const withTail = (parts) => [...parts.map((p) => p.text), ...(sigTail ? [sigTail] : [])].join('\n');
4552
+ emitFileSection({
4553
+ header: fileSectionHeader(filePath, `${names} · ${tag}`),
4554
+ body: dd.parts.length > 0 ? withTail(dd.parts) : '',
4555
+ ranges: dd.parts.map((p) => p.range),
4556
+ covered: dd.covered,
4557
+ overhead: 120,
4558
+ mode: bodyIds.size > 0 ? 'focused' : 'skeleton',
4559
+ // Always "clipped": the per-symbol view elides bodies by construction.
4560
+ clipped: true,
4561
+ fullBody: withTail(skel),
4562
+ fullRanges: skel.map((p) => p.range),
4563
+ });
3203
4564
  continue;
3204
4565
  }
3205
4566
  }
@@ -3217,36 +4578,142 @@ class ToolHandler {
3217
4578
  // the ceiling and falls through to sectioning/clustering below — full method
3218
4579
  // bodies + signatures — so we never dump (or overflow on) a whole god-file.
3219
4580
  const isCentralFile = centralFiles.has(filePath);
3220
- // Central files get a slightly larger whole-file window than peripheral ones,
3221
- // but a TIGHT one (~1.5× the per-file cap): the native read of a central file
3222
- // is a ~150–250 line orientation window, NOT the whole file. A flat "whole
3223
- // central file" both overflowed the inline cap AND starved the co-flow files
3224
- // (worker.rs ate the budget, dropping harness.rs's poll). A larger central
3225
- // file falls through to per-method windowing/clustering below.
4581
+ // A file ships whole when it fits its RESERVATION (plus a small grace — see
4582
+ // WHOLE_FILE_GRACE). This is the site of the #1500 allocation bug: the
4583
+ // peripheral bound used to be a flat `maxCharsPerFile * 3`, so ANY file under
4584
+ // ~11K shipped its entire contents regardless of relevance, while a
4585
+ // high-scoring file too big for that window was clipped to `maxCharsPerFile`
4586
+ // — a 3x swing decided by file size alone. Tying both bounds to the
4587
+ // reservation removes the swing without touching the rule's purpose (a small
4588
+ // file sliced is a lossy subset the agent just Reads in full anyway).
3226
4589
  const WHOLE_FILE_MAX_LINES = isCentralFile ? 280 : 220;
3227
- const WHOLE_FILE_MAX_CHARS = isCentralFile
3228
- ? Math.min(Math.max(0, budget.maxOutputChars - totalChars - 200), Math.round(budget.maxCharsPerFile * 1.5))
3229
- : budget.maxCharsPerFile * 3;
3230
- if (fileLines.length <= WHOLE_FILE_MAX_LINES && fileContent.length <= WHOLE_FILE_MAX_CHARS) {
4590
+ // Two bounds, whichever is larger (CG-21):
4591
+ // GRACE — the reservation plus a sliver, for a file that essentially fits;
4592
+ // BUY — the reservation already covers most of the file, so the rest is
4593
+ // cheaper to ship than to lose. A file between the two used to
4594
+ // fall through to clustering and then spend a FRACTION of its
4595
+ // reservation, and the remainder was neither delivered nor
4596
+ // redistributed. See WHOLE_FILE_BUY_FRACTION.
4597
+ //
4598
+ // The BUY arm is two independent tests, and keeping them apart is the whole
4599
+ // design. MERIT reads `reserved` — did THIS file's own relevance earn most
4600
+ // of itself? — so borrowed slack can never promote a weak file to whole.
4601
+ // FUNDING reads the shared overshoot pool, so the bytes exist to pay for it.
4602
+ // Slack still reaches the file through `allowance`: it raises the GRACE arm
4603
+ // and shrinks what a buy has to borrow.
4604
+ const graceBound = allowance + Math.min(exports.EXPLORE_ALLOCATION.WHOLE_FILE_GRACE_MAX, Math.round(allowance * exports.EXPLORE_ALLOCATION.WHOLE_FILE_GRACE_FRACTION));
4605
+ // FUNDING, as one inequality: after this file ships whole, does the source
4606
+ // still fit the promise-plus-overshoot line WITH every reservation below
4607
+ // it left payable? `owedBelow` is what makes it a displacement guard
4608
+ // rather than a size cap — a buy that fits the line only by spending a
4609
+ // lower-ranked file's reservation is the trade that dropped
4610
+ // `payslip_builder.go`, and it is refused here. Self-limiting: each buy
4611
+ // grows `sourceSpent`, so the pool cannot be spent twice. The cluster path
4612
+ // below enforces the same inequality in render space — see
4613
+ // `fundedHeadroom` / `owedPayableBelow` (CG-31).
4614
+ const owedBelow = Math.max(0, reservedTotal - reservedSoFar);
4615
+ // Third condition on the BUY arm only: it must also FIT. A whole render
4616
+ // that overruns the ceiling is skipped ENTIRELY (the branch refuses to
4617
+ // slice a file mid-method), so attempting a buy that cannot fit trades a
4618
+ // clustered section for NO section — the same trade the funding pool
4619
+ // exists to refuse, arriving by a different route. Failing the test here
4620
+ // instead drops through to the cluster path, which is bounded by
4621
+ // `fundedHeadroom` and always renders something.
4622
+ //
4623
+ // Measured against `fundedHeadroom`, not against `renderCeiling - totalChars`
4624
+ // (CG-26). The two differ by exactly the displacement term: room before
4625
+ // the ceiling belongs to every file the loop has not reached yet, and
4626
+ // this arm used to read the raw room while its source-space sibling
4627
+ // (`owedBelow`, above) refused the same trade. Source-space alone was not
4628
+ // enough — the funding line is `reservedTotal + 0.15 * envelope` (~27.2K
4629
+ // when a medium repo saturates) while the render ceiling is ~24.2K, so a
4630
+ // buy can clear `sourceCeiling` and still take its bytes out of a
4631
+ // lower-ranked file's reservation on the way to the ceiling. Now both
4632
+ // arms enforce the same inequality in their own units, and the invariant
4633
+ // holds on every path.
4634
+ //
4635
+ // The GRACE arm keeps its own bound (a file within a sliver of its
4636
+ // reservation) but is fit-tested on the render it actually produces, at
4637
+ // the emission site below, so it cannot displace either.
4638
+ const buysWhole = fileContent.length <= graceBound
4639
+ || (reserved >= fileContent.length * exports.EXPLORE_ALLOCATION.WHOLE_FILE_BUY_FRACTION
4640
+ && sourceSpent + fileContent.length + owedBelow <= sourceCeiling
4641
+ && fileContent.length <= fundedHeadroom);
4642
+ // Set by the whole-file arm when it actually emits. A whole render that
4643
+ // does not FIT no longer ends the file's turn (CG-26) — it falls through
4644
+ // to the cluster path below, which is bounded by `fundedHeadroom` and
4645
+ // renders something. Skipping outright was the trade the funding pool
4646
+ // exists to refuse: a clustered section traded for no section at all.
4647
+ let renderedWhole = false;
4648
+ if (fileLines.length <= WHOLE_FILE_MAX_LINES && buysWhole) {
3231
4649
  const body = fileContent.replace(/\n+$/, '');
3232
- let wholeSection = exploreLineNumbersEnabled() ? numberSourceLines(body, 1) : body;
4650
+ const wholeRange = { start: 1, end: body.split('\n').length };
4651
+ const fullSection = withLineNumbers ? numberSourceLines(body, 1) : body;
4652
+ // The buy decision above was made on the file's FULL size on purpose: it
4653
+ // asks "did this file's relevance earn all of itself", which dedup does
4654
+ // not change. Dedup then only ever makes the render smaller, so a buy
4655
+ // that was funded stays funded.
4656
+ const ddWhole = dedupeSpans([{ range: wholeRange, text: fullSection }]);
4657
+ const wholeSection = ddWhole.parts.map((p) => p.text).join(GAP_MARKER);
3233
4658
  const uniqSymbols = [...new Set(group.nodes
3234
4659
  .filter(n => n.kind !== 'import' && n.kind !== 'export')
3235
4660
  .map(n => `${n.name}(${n.kind})`))];
3236
4661
  const headerNames = uniqSymbols.slice(0, budget.maxSymbolsInFileHeader);
3237
4662
  const omitted = uniqSymbols.length - headerNames.length;
3238
- const wholeHeader = fileSectionHeader(filePath, omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', '));
3239
- if (!fileNecessary && totalChars + wholeSection.length + 200 > budget.maxOutputChars) {
3240
- // Don't slice a whole file mid-method: an incidental file that doesn't
3241
- // fit is skipped; a necessary one (below) renders in full. Half a file
3242
- // forces the Read this is meant to prevent.
4663
+ // A drifted file rendered WHOLE is still correct (current bytes,
4664
+ // numbered from 1) — only the index-derived symbol list / line refs to
4665
+ // it elsewhere in this response may be shifted (#1474). Flag that.
4666
+ const staleSuffix = fileStale ? ' · ⚠ changed since last index sync — source below is current; the symbol list may be outdated' : '';
4667
+ const wholeHeader = fileSectionHeader(filePath, (omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', ')) + staleSuffix);
4668
+ // The fit test, on the bytes this render ACTUALLY costs (the numbered
4669
+ // body, after dedup) rather than on the raw file — and against
4670
+ // `fundedHeadroom`, so a whole render can no more spend a pending
4671
+ // file's reservation than a clustered one can (CG-26). Both whole-file
4672
+ // arms come through here, which is what closes the invariant on the
4673
+ // GRACE path: grace is measured against this file's own allowance and
4674
+ // says nothing about whether the bytes are still there to spend.
4675
+ // Two tests, and they are different questions. `fundedHeadroom` is the
4676
+ // DISPLACEMENT bound — may these bytes be spent without taking a
4677
+ // pending file's reservation. `sectionCost` is the CEILING bound — do
4678
+ // the header, fences and body actually fit what is left. The second one
4679
+ // is exact now that the loop charges real section costs.
4680
+ const wholeCost = wholeHeader.length + 2 + wholeSection.length + lang.length + 11;
4681
+ if (wholeSection.length <= fundedHeadroom && totalChars + wholeCost <= renderCeiling) {
4682
+ emitFileSection({
4683
+ header: wholeHeader,
4684
+ body: wholeSection,
4685
+ // The whole file, minus any trailing blank lines the render trimmed.
4686
+ ranges: ddWhole.parts.map((p) => p.range),
4687
+ covered: ddWhole.covered,
4688
+ overhead: 200,
4689
+ mode: 'whole',
4690
+ clipped: false,
4691
+ fullBody: fullSection,
4692
+ fullRanges: [wholeRange],
4693
+ });
4694
+ if (fileStale)
4695
+ staleRendered.push(filePath);
4696
+ renderedWhole = true;
4697
+ }
4698
+ else {
4699
+ // Doesn't fit whole — don't slice a whole file mid-method here; fall
4700
+ // through and let the cluster path pick body-shaped pieces of it.
3243
4701
  anyFileTrimmed = true;
3244
- continue;
3245
4702
  }
3246
- lines.push(wholeHeader, '', '```' + lang, wholeSection, '```', '');
3247
- totalChars += wholeSection.length + 200;
3248
- renderedFilePaths.push(filePath);
3249
- filesIncluded++;
4703
+ }
4704
+ if (renderedWhole)
4705
+ continue;
4706
+ // Drifted file too big for the whole-file window (#1474): the cluster /
4707
+ // skeleton renders below would slice current bytes at indexed ranges —
4708
+ // on a shifted file that serves a DIFFERENT symbol's code under the
4709
+ // requested name. Omit the source with an explicit notice instead;
4710
+ // never render a possibly-wrong slice.
4711
+ if (fileStale) {
4712
+ staleOmitted.push(filePath);
4713
+ const staleHeader = fileSectionHeader(filePath, '⚠ changed on disk after the last index sync — source omitted (indexed line ranges no longer match, so a slice could show the wrong code). Read this file directly for current content; the change is picked up on that project\'s next index sync.');
4714
+ lines.push(staleHeader, '');
4715
+ totalChars += staleHeader.length + 2;
4716
+ diag?.recordRender(filePath, 'stale-omitted', 0, true);
3250
4717
  continue;
3251
4718
  }
3252
4719
  // Cluster nearby symbols to avoid reading huge gaps between distant symbols.
@@ -3268,7 +4735,7 @@ class ToolHandler {
3268
4735
  // query actually asked about (#185 follow-up — Session.swift in
3269
4736
  // Alamofire is the canonical case: the `Session` class spans ~1,400
3270
4737
  // lines). We want the granular symbols inside, not the envelope.
3271
- const ENVELOPE_KINDS = new Set(['file', 'module', 'class', 'struct', 'interface', 'enum', 'namespace', 'protocol', 'trait', 'component']);
4738
+ const ENVELOPE_KINDS = new Set(['file', 'module', 'class', 'struct', 'union', 'interface', 'enum', 'namespace', 'protocol', 'trait', 'component']);
3272
4739
  // Cluster from this file's gathered nodes PLUS any callable the agent NAMED that
3273
4740
  // lives here. Explore's relevance gather can miss a named method def in a huge
3274
4741
  // non-sibling file — Django's query.py is 3,040 lines and `_fetch_all` (L2237)
@@ -3328,8 +4795,10 @@ class ToolHandler {
3328
4795
  }
3329
4796
  }
3330
4797
  ranges.sort((a, b) => a.start - b.start);
3331
- if (ranges.length === 0)
4798
+ if (ranges.length === 0) {
4799
+ diag?.recordSkip(filePath, 'no-ranges');
3332
4800
  continue;
4801
+ }
3333
4802
  const gapThreshold = budget.gapThreshold;
3334
4803
  const clusters = [];
3335
4804
  let current = {
@@ -3340,6 +4809,7 @@ class ToolHandler {
3340
4809
  maxImportance: ranges[0].importance,
3341
4810
  hasSpine: ranges[0].spine,
3342
4811
  spineCallLine: ranges[0].spineCallLine,
4812
+ members: [ranges[0]],
3343
4813
  };
3344
4814
  for (let i = 1; i < ranges.length; i++) {
3345
4815
  const r = ranges[i];
@@ -3350,6 +4820,7 @@ class ToolHandler {
3350
4820
  current.maxImportance = Math.max(current.maxImportance, r.importance);
3351
4821
  current.hasSpine = current.hasSpine || r.spine;
3352
4822
  current.spineCallLine = current.spineCallLine ?? r.spineCallLine;
4823
+ current.members.push(r);
3353
4824
  }
3354
4825
  else {
3355
4826
  clusters.push(current);
@@ -3361,6 +4832,7 @@ class ToolHandler {
3361
4832
  maxImportance: r.importance,
3362
4833
  hasSpine: r.spine,
3363
4834
  spineCallLine: r.spineCallLine,
4835
+ members: [r],
3364
4836
  };
3365
4837
  }
3366
4838
  }
@@ -3373,10 +4845,6 @@ class ToolHandler {
3373
4845
  // until the per-file char cap is hit. Truly enormous single clusters
3374
4846
  // get tail-trimmed with a marker.
3375
4847
  const contextPadding = 3;
3376
- const withLineNumbers = exploreLineNumbersEnabled();
3377
- // Language-neutral separator (no `//` — not a comment in Python, Ruby,
3378
- // etc.). With line numbers on, the line-number jump also signals the gap.
3379
- const GAP_MARKER = '\n\n... (gap) ...\n\n';
3380
4848
  // An oversize spine method (the call path runs THROUGH a god-method — n8n's
3381
4849
  // processRunExecutionData is 962 lines) is windowed to its next-hop CALL site
3382
4850
  // plus the signature head, NOT dumped whole. Without this the cluster is too big
@@ -3385,6 +4853,7 @@ class ToolHandler {
3385
4853
  // the spine's call still appears in context.
3386
4854
  const OVERSIZE_SPINE_LINES = 200;
3387
4855
  const SPINE_WINDOW = 28; // lines each side of the next-hop call site
4856
+ const sectionText = (parts) => parts.map((p) => p.text).join(GAP_MARKER);
3388
4857
  const buildSection = (c) => {
3389
4858
  if (c.hasSpine && c.spineCallLine && (c.end - c.start + 1) > OVERSIZE_SPINE_LINES) {
3390
4859
  const call = c.spineCallLine;
@@ -3396,17 +4865,290 @@ class ToolHandler {
3396
4865
  const headEnd = Math.min(c.start + 4, winStart - 2);
3397
4866
  if (headEnd >= c.start) {
3398
4867
  const head = fileLines.slice(c.start - 1, headEnd).join('\n');
3399
- parts.push(withLineNumbers ? numberSourceLines(head, c.start) : head);
4868
+ parts.push({
4869
+ range: { start: c.start, end: headEnd },
4870
+ text: withLineNumbers ? numberSourceLines(head, c.start) : head,
4871
+ });
3400
4872
  }
3401
4873
  const win = fileLines.slice(winStart - 1, winEnd).join('\n');
3402
- parts.push(withLineNumbers ? numberSourceLines(win, winStart) : win);
3403
- return parts.join(GAP_MARKER);
4874
+ parts.push({
4875
+ range: { start: winStart, end: winEnd },
4876
+ text: withLineNumbers ? numberSourceLines(win, winStart) : win,
4877
+ });
4878
+ return parts;
3404
4879
  }
3405
4880
  const startIdx = Math.max(0, c.start - 1 - contextPadding);
3406
4881
  const endIdx = Math.min(fileLines.length, c.end + contextPadding);
3407
4882
  const slice = fileLines.slice(startIdx, endIdx).join('\n');
3408
4883
  // startIdx is 0-based, so the slice's first line is line startIdx + 1.
3409
- return withLineNumbers ? numberSourceLines(slice, startIdx + 1) : slice;
4884
+ return [{
4885
+ range: { start: startIdx + 1, end: endIdx },
4886
+ text: withLineNumbers ? numberSourceLines(slice, startIdx + 1) : slice,
4887
+ }];
4888
+ };
4889
+ /**
4890
+ * Shrink an oversize cluster to the highest-importance symbols inside it
4891
+ * that fit `cap`, rendered in source order with gap markers (CG-12).
4892
+ *
4893
+ * A cluster is a MERGE of whole symbol ranges, and on a densely-packed file
4894
+ * every symbol merges into one blob spanning the file — cycle.go's 209-line
4895
+ * `Service` is one cluster covering `RunCycle`, `runPayrollCycleAll` and
4896
+ * seven incidental accessors. The old rule took the top-ranked cluster whole
4897
+ * however big it was, so a single-cluster file simply ignored its budget:
4898
+ * it took ~40% more than it was allotted, and the file below it was then
4899
+ * dropped for lack of room (that is how `BuildPayslip` — the "calculate"
4900
+ * half of the #1500 query — went missing entirely). Shrinking by MEMBER
4901
+ * keeps every rule that matters: only whole symbol ranges are emitted, so a
4902
+ * body is never cut, and the members are chosen by the same importance the
4903
+ * cluster ranking uses. Returns null when nothing needed shrinking.
4904
+ *
4905
+ * `sizeOf` measures the RAW source span, while the render adds
4906
+ * `contextPadding` around every block and a line-number prefix to every
4907
+ * line — so this over-keeps (measured ~60% under on a 1,414-line file:
4908
+ * 16.5K accounted, 26.3K rendered). That is deliberate, not an oversight:
4909
+ * `bound()` clamps the result to the ceiling exactly, so the slack costs no
4910
+ * bytes, and making the estimate exact instead measured WORSE — it stops at
4911
+ * the last member that fits whole, and the released bytes carry forward to
4912
+ * lower-ranked files (payroll-go's `runPayrollCycleAll` body lost its
4913
+ * `s.store.Upsert` call to a rank-5 file). What the slack must NOT do is
4914
+ * decide WHICH members survive: that is the ceiling trim's job, and CG-38 is
4915
+ * why that trim now protects the named spans instead of cutting in source
4916
+ * order. See `docs/benchmarks/explore-tail-render-cg38.md`.
4917
+ */
4918
+ const shrinkCluster = (c, cap) => {
4919
+ if (c.members.length < 2)
4920
+ return null;
4921
+ const byImportance = [...c.members].sort((a, b) => b.importance - a.importance || (a.end - a.start) - (b.end - b.start) || a.start - b.start);
4922
+ const sizeOf = (r) => fileLines.slice(r.start - 1, r.end).join('\n').length;
4923
+ const keep = [];
4924
+ let kept = 0;
4925
+ for (const r of byImportance) {
4926
+ const sz = sizeOf(r) + GAP_MARKER.length;
4927
+ // Always keep the most important range, even if it alone is oversize —
4928
+ // an empty section sends the agent to Read, which costs far more. How
4929
+ // far it may overshoot is bounded by the caller's ceiling (CG-30), which
4930
+ // windows a runaway member instead of dropping it.
4931
+ if (keep.length > 0 && kept + sz > cap)
4932
+ continue;
4933
+ keep.push(r);
4934
+ kept += sz;
4935
+ }
4936
+ if (keep.length === c.members.length)
4937
+ return null;
4938
+ // Re-merge the kept ranges in source order so adjacent survivors read as
4939
+ // one block rather than a stutter of one-symbol fragments.
4940
+ keep.sort((a, b) => a.start - b.start);
4941
+ const merged = [];
4942
+ for (const r of keep) {
4943
+ const last = merged[merged.length - 1];
4944
+ if (last && r.start <= last.end + gapThreshold)
4945
+ last.end = Math.max(last.end, r.end);
4946
+ else
4947
+ merged.push({ start: r.start, end: r.end });
4948
+ }
4949
+ return merged.flatMap((m) => buildSection(m));
4950
+ };
4951
+ /**
4952
+ * Bounded overshoot for one cluster's render (CG-30).
4953
+ *
4954
+ * `shrinkCluster` keeps the highest-importance member whole even when that
4955
+ * member alone is oversize — an empty file section sends the agent to Read,
4956
+ * which is exactly what explore exists to prevent. But "never empty" is not
4957
+ * "any size": with nothing bounding it, one 22K member rendered against a
4958
+ * 9K reservation (2.4x), which collapses the headroom every file ranked
4959
+ * below it draws from. Past the ceiling the member is WINDOWED rather than
4960
+ * dropped — a leading window (signature + head of the body), plus a window
4961
+ * on the spine's call site when the head misses it, since on a flow cluster
4962
+ * the call path IS the answer.
4963
+ */
4964
+ const MIN_WINDOW_LINES = 12;
4965
+ /** Rendered cost of one source line, line numbering included. */
4966
+ const lineCost = (ln) => (fileLines[ln - 1] ?? '').length + 1 + (withLineNumbers ? String(ln).length + 1 : 0);
4967
+ /**
4968
+ * Longest prefix of `r` that fits `room`. `minLines` is the never-empty
4969
+ * floor — it may overrun `room`, so it is only ever asked for when nothing
4970
+ * else has been emitted and the alternative is an empty section.
4971
+ */
4972
+ const headWindowOf = (r, room, minLines = 0) => {
4973
+ let end = r.start - 1;
4974
+ let chars = 0;
4975
+ for (let ln = r.start; ln <= r.end; ln++) {
4976
+ const cost = lineCost(ln);
4977
+ if (chars + cost > room && end - r.start + 1 >= minLines)
4978
+ break;
4979
+ chars += cost;
4980
+ end = ln;
4981
+ }
4982
+ return end >= r.start ? { start: r.start, end } : null;
4983
+ };
4984
+ /** Widest window around `line` inside [lo, hi] that fits `room`. */
4985
+ const centeredWindowOf = (line, lo, hi, room) => {
4986
+ if (line < lo || line > hi)
4987
+ return null;
4988
+ let start = line, end = line, chars = lineCost(line);
4989
+ for (let grown = true; grown;) {
4990
+ grown = false;
4991
+ if (end + 1 <= hi && chars + lineCost(end + 1) <= room) {
4992
+ end += 1;
4993
+ chars += lineCost(end);
4994
+ grown = true;
4995
+ }
4996
+ if (start - 1 >= lo && chars + lineCost(start - 1) <= room) {
4997
+ start -= 1;
4998
+ chars += lineCost(start);
4999
+ grown = true;
5000
+ }
5001
+ }
5002
+ return { start, end };
5003
+ };
5004
+ /**
5005
+ * Reduce rendered parts to fit `ceiling`, never to nothing. Whole parts are
5006
+ * kept while they fit; the first part that overruns is cut to a leading
5007
+ * window on whole lines (a body is never cut mid-line), and everything past
5008
+ * it is dropped. The GAP_MARKER between surviving parts — and the line-number
5009
+ * jump — is what tells the agent the cut happened.
5010
+ *
5011
+ * A partial window shorter than MIN_WINDOW_LINES is not worth emitting, and
5012
+ * emitting one is actively harmful: the session record then claims a 4-line
5013
+ * sliver, and the NEXT call's dedup has to either shred a whole block around
5014
+ * it or re-send it. Below that floor the part is simply dropped — unless
5015
+ * nothing has been emitted at all, where the floor wins over the ceiling
5016
+ * because an empty section is the one outcome worse than an oversize one.
5017
+ *
5018
+ * `focusLines` are the lines this trim must not lose: the spine's next-hop
5019
+ * call site (CG-30) and every definition the agent NAMED inside the cluster
5020
+ * (CG-38). The head fill is source-ordered, so a named def in the TAIL of a
5021
+ * large file is otherwise always the first thing an over-ceiling render
5022
+ * drops — the one span the agent asked for by name, cut in favour of
5023
+ * head-of-file filler it did not ask for. The full-ceiling fill is tried
5024
+ * FIRST and the 60% hold-back applies only when a focus line is actually
5025
+ * left uncovered, so a cluster whose head already reaches its focus keeps
5026
+ * the whole ceiling for source.
5027
+ */
5028
+ const windowToCeiling = (parts, ceiling, focusLines = []) => {
5029
+ const inParts = (line) => parts.some((p) => line >= p.range.start && line <= p.range.end);
5030
+ const focus = [...new Set(focusLines)]
5031
+ .filter((l) => typeof l === 'number' && l > 0 && inParts(l))
5032
+ .sort((a, b) => a - b);
5033
+ /** Source-ordered fill of whole parts, the overrunning one cut to a head window. */
5034
+ const fill = (room) => {
5035
+ const emit = [];
5036
+ let used = 0;
5037
+ for (const p of parts) {
5038
+ const join = emit.length > 0 ? GAP_MARKER.length : 0;
5039
+ if (used + join + p.text.length <= room) {
5040
+ emit.push(p.range);
5041
+ used += join + p.text.length;
5042
+ continue;
5043
+ }
5044
+ const first = emit.length === 0;
5045
+ const win = headWindowOf(p.range, Math.max(0, room - used - join), first ? MIN_WINDOW_LINES : 0);
5046
+ if (win && (first || win.end - win.start + 1 >= MIN_WINDOW_LINES)) {
5047
+ emit.push(win);
5048
+ used += join + renderSpan(win).length;
5049
+ }
5050
+ break;
5051
+ }
5052
+ return { emit, used };
5053
+ };
5054
+ let { emit, used } = fill(ceiling);
5055
+ const reached = () => (emit.length ? emit[emit.length - 1].end : 0);
5056
+ if (focus.some((l) => l > reached())) {
5057
+ // Hold room back for the focus windows so the head can't eat all of it.
5058
+ ({ emit, used } = fill(Math.floor(ceiling * 0.6)));
5059
+ }
5060
+ // What is left is SPLIT between the uncovered focus lines rather than
5061
+ // handed to them in order. Greedy-in-source-order reproduces the very bug
5062
+ // this guards: on a prose query resolving four focus lines, the two
5063
+ // earliest took the whole reserve and `flushQueuedMessages` at L1102 —
5064
+ // named in the question — was dropped again. A skipped or undersized
5065
+ // window returns its share to the pool for the ones after it.
5066
+ let covered = reached();
5067
+ let room = Math.max(0, ceiling - used);
5068
+ const pending = focus.filter((l) => l > covered);
5069
+ for (let i = 0; i < pending.length; i++) {
5070
+ const line = pending[i];
5071
+ if (line <= covered)
5072
+ continue; // an earlier window already reached it
5073
+ const share = Math.floor(room / (pending.length - i)) - GAP_MARKER.length;
5074
+ if (share <= 0)
5075
+ continue;
5076
+ const host = parts.find((p) => line >= p.range.start && line <= p.range.end);
5077
+ const lo = Math.max(host.range.start, line - SPINE_WINDOW, covered + 1);
5078
+ const hi = Math.min(host.range.end, line + SPINE_WINDOW);
5079
+ const win = centeredWindowOf(line, lo, hi, share);
5080
+ // Same sliver floor as the head window — a two-line peek at the call
5081
+ // site teaches the next call's dedup to shred the block around it.
5082
+ if (!win || win.end - win.start + 1 < MIN_WINDOW_LINES)
5083
+ continue;
5084
+ emit.push(win);
5085
+ const cost = GAP_MARKER.length + renderSpan(win).length;
5086
+ used += cost;
5087
+ room -= cost;
5088
+ covered = win.end;
5089
+ }
5090
+ // Never empty: a section with no source sends the agent to Read.
5091
+ if (emit.length === 0 && parts.length > 0) {
5092
+ const first = headWindowOf(parts[0].range, ceiling, MIN_WINDOW_LINES);
5093
+ if (first)
5094
+ emit.push(first);
5095
+ }
5096
+ return emit
5097
+ .sort((a, b) => a.start - b.start)
5098
+ .map((r) => ({ range: r, text: renderSpan(r) }));
5099
+ };
5100
+ /**
5101
+ * The lines a ceiling trim of this cluster must not lose: the spine's
5102
+ * next-hop call site, and the definition line of every member the agent
5103
+ * NAMED or that is a query entry point (importance >= 9). Capped, because
5104
+ * each one costs a window and too many turn a section into confetti; the
5105
+ * most important come first, source order within a tier so the windows read
5106
+ * top-down.
5107
+ */
5108
+ const MAX_FOCUS_LINES = 6;
5109
+ const focusLinesOf = (c) => {
5110
+ const named = c.members
5111
+ .filter((m) => m.importance >= 9)
5112
+ .sort((a, b) => b.importance - a.importance || a.start - b.start)
5113
+ .slice(0, MAX_FOCUS_LINES)
5114
+ .map((m) => m.start);
5115
+ return c.spineCallLine ? [c.spineCallLine, ...named] : named;
5116
+ };
5117
+ /**
5118
+ * One cluster's final parts: built, shrunk if it overruns `cap`, then
5119
+ * passed through the session history (CG-18).
5120
+ *
5121
+ * The shrink decision reads the DEDUPED length on purpose. A cluster whose
5122
+ * bytes the agent already holds costs this response nothing, so shrinking
5123
+ * it on its raw size would drop new symbols to make room for source that
5124
+ * is not being sent — spending the file's budget on nothing.
5125
+ */
5126
+ const renderCluster = (c, cap,
5127
+ /**
5128
+ * Hard bound on the rendered result (CG-30). `cap` is what selection asks
5129
+ * for; this is how far a single oversize member is allowed to overshoot it
5130
+ * before being windowed. Always >= `cap`, so a cluster that already fits is
5131
+ * never touched.
5132
+ */
5133
+ ceiling = Infinity) => {
5134
+ const base = dedupeSpans(buildSection(c));
5135
+ const bound = (r) => {
5136
+ if (!Number.isFinite(ceiling) || sectionText(r.parts).length <= ceiling)
5137
+ return r;
5138
+ // Windows are subsets of spans dedupeSpans already cleared, so the record
5139
+ // still only ever claims source that was actually sent.
5140
+ const parts = windowToCeiling(r.parts, ceiling, focusLinesOf(c));
5141
+ return { parts, covered: r.covered, shrunk: true };
5142
+ };
5143
+ if (sectionText(base.parts).length <= cap) {
5144
+ return { parts: base.parts, covered: base.covered, shrunk: false };
5145
+ }
5146
+ const shrunk = shrinkCluster(c, cap);
5147
+ if (shrunk === null) {
5148
+ return bound({ parts: base.parts, covered: base.covered, shrunk: false });
5149
+ }
5150
+ const dd = dedupeSpans(shrunk);
5151
+ return bound({ parts: dd.parts, covered: dd.covered, shrunk: true });
3410
5152
  };
3411
5153
  // Rank clusters for inclusion under the per-file cap. Entry-point
3412
5154
  // clusters come first: a cluster containing a query entry point
@@ -3437,106 +5179,327 @@ class ToolHandler {
3437
5179
  return b.c.score - a.c.score;
3438
5180
  return a.span - b.span;
3439
5181
  });
3440
- // Per-file budget is the SMALLER of the per-file cap and what's left of the
3441
- // total output cap — so selection (which ranks by importance) keeps the
5182
+ // Per-file budget is this file's RESERVATION, bounded by what's left before
5183
+ // the hard ceiling — so selection (which ranks by importance) keeps the
3442
5184
  // high-importance clusters and drops peripheral ones, instead of the
3443
5185
  // downstream source-order trim slicing off whatever comes last in the file.
3444
5186
  // That source-order slice is what cut Django's `_fetch_all` (L2237, importance
3445
5187
  // 9 — agent-named) when query.py was the last of four big files to be emitted.
3446
- const fileBudget = Math.min(budget.maxCharsPerFile, Math.max(0, budget.maxOutputChars - totalChars - 200));
3447
- // Spine ceiling: a flow-path cluster may exceed the per-file cap (the call
3448
- // path is the answer), but bounded — at most ~2.5× the per-file cap and never
3449
- // past what's left of the total output cap — so a pathological long in-file
3450
- // spine can't run away or starve co-flow files entirely.
3451
- const SPINE_CEILING = Math.min(budget.maxCharsPerFile * 2.5, Math.max(0, budget.maxOutputChars - totalChars - 200));
5188
+ // It used to be `min(maxCharsPerFile, remaining)`: a flat cap that clipped the
5189
+ // top-scoring file at the same 3,800 as the weakest one, while the whole-file
5190
+ // branch above handed a small file 3x that. The reservation is the whole point
5191
+ // of CG-12 — bytes follow relevance, not file size.
5192
+ //
5193
+ // `fundedHeadroom`, not `headroom` (CG-31): what is left before the hard
5194
+ // ceiling includes every unreached file's reservation, and spending that
5195
+ // is how one clustered file zeroed five admitted peers. It is ≤ `headroom`
5196
+ // by construction, so it is the only bound these three lines need.
5197
+ const fileBudget = Math.min(allowance, fundedHeadroom);
5198
+ // Spine ceiling: a flow-path cluster may exceed the reservation (the call path
5199
+ // IS the answer and clipping it forces the Read), but bounded — 1.5x the
5200
+ // reservation and never past the ceiling — so a pathological long in-file
5201
+ // spine can't run away or starve co-flow files entirely. The 1.5x is drawn
5202
+ // from the shared envelope, so it is exactly the overshoot the displacement
5203
+ // guard has to fund: past `fundedHeadroom` the extra half-reservation is
5204
+ // another file's, not spare room.
5205
+ const SPINE_CEILING = Math.min(Math.round(allowance * 1.5), fundedHeadroom);
3452
5206
  const chosenIndices = new Set();
5207
+ // Final renders (deduped, shrunk where oversize) by cluster index. Computed
5208
+ // during selection and reused at emission so the two never disagree.
5209
+ const renderedClusters = new Map();
5210
+ let anyClusterShrunk = false;
3453
5211
  let projectedChars = 0;
3454
5212
  for (const rc of rankedClusters) {
3455
- const sectionLen = buildSection(rc.c).length + (chosenIndices.size > 0 ? GAP_MARKER.length : 0);
3456
- // Always take the top-ranked cluster, even if oversize, so we don't
3457
- // return an empty file section (agent would then re-Read the file,
3458
- // negating the savings).
3459
- if (chosenIndices.size === 0) {
5213
+ // The top-ranked cluster is always taken — an empty file section sends the
5214
+ // agent to Read, negating the savings. But "always taken" is not "taken at
5215
+ // any size": when it overruns the reservation it is SHRUNK to the
5216
+ // highest-importance whole symbol ranges inside it, so a single-cluster
5217
+ // god-file spends its allotment instead of the whole response's.
5218
+ const first = chosenIndices.size === 0;
5219
+ // A spine cluster (the rendered call path) is the flow answer — it may run
5220
+ // past the per-file budget up to the spine ceiling; non-spine clusters obey
5221
+ // the normal per-file budget.
5222
+ const cap = rc.c.hasSpine ? SPINE_CEILING : fileBudget;
5223
+ // CG-30: shrinking keeps the top member whole however big it is, so bound
5224
+ // how far that member may overshoot — the same 1.5x-of-reservation bound
5225
+ // SPINE_CEILING already draws, never below `cap` (a cluster that fits its
5226
+ // cap is never windowed). A spine cluster's cap already IS that bound, so
5227
+ // this holds it to it rather than letting the member rule walk past it.
5228
+ const ceiling = Math.max(cap, SPINE_CEILING);
5229
+ if (first) {
5230
+ const section = renderCluster(rc.c, cap, ceiling);
5231
+ renderedClusters.set(rc.idx, section);
5232
+ anyClusterShrunk = anyClusterShrunk || section.shrunk;
3460
5233
  chosenIndices.add(rc.idx);
3461
- projectedChars += sectionLen;
5234
+ projectedChars += sectionText(section.parts).length;
3462
5235
  continue;
3463
5236
  }
3464
- // A spine cluster (the rendered call path) is the flow answer — include it
3465
- // past the per-file budget up to the spine ceiling; non-spine clusters obey
3466
- // the normal per-file budget.
3467
- const fits = projectedChars + sectionLen <= fileBudget;
3468
- const spineFits = rc.c.hasSpine && projectedChars + sectionLen <= SPINE_CEILING;
3469
- if (!fits && !spineFits)
5237
+ // Later clusters used to be all-or-nothing: rendered whole, then taken
5238
+ // only if the whole thing fit the remainder. On a file whose top-ranked
5239
+ // cluster is TRIVIAL that discards the answer and leaves the reservation
5240
+ // unspent — django's `sql/query.py` keeps a 22-line glue cluster (one
5241
+ // importance-6 bridging symbol) and drops the 624-line `Query` body
5242
+ // beneath it whole, spending 1,923 of 7,947; the slack then carries
5243
+ // forward to a file scoring a fifth as much (CG-36). Same shape in
5244
+ // okhttp's `RealInterceptorChain.kt`, where an import header displaces
5245
+ // the chain itself.
5246
+ //
5247
+ // So a later cluster is shrunk INTO the remainder by the same whole-member
5248
+ // rule the first one already uses — CG-26's between-FILES lesson ("hold the
5249
+ // remainder while it is still worth a section; zeroing it delivers
5250
+ // nothing") applied between CLUSTERS. Below `MIN_CHARS` the remainder can't
5251
+ // hold one readable block, so it stays a drop rather than a stutter of
5252
+ // fragments the next call's dedup then has to shred around.
5253
+ const room = cap - projectedChars - GAP_MARKER.length;
5254
+ if (room < exports.EXPLORE_ALLOCATION.MIN_CHARS)
5255
+ continue;
5256
+ const section = renderCluster(rc.c, room, room);
5257
+ const text = sectionText(section.parts);
5258
+ if (text.length === 0)
3470
5259
  continue;
5260
+ // The never-empty floors inside the windowing may overrun `room` (a
5261
+ // 12-line minimum window on a file of very long lines). The first cluster
5262
+ // is allowed that overshoot — an empty section is worse — but a later one
5263
+ // is not: it would be spending a lower-ranked FILE's reservation for a
5264
+ // fragment. Drop it, exactly as before.
5265
+ if (projectedChars + text.length + GAP_MARKER.length > cap)
5266
+ continue;
5267
+ renderedClusters.set(rc.idx, section);
5268
+ anyClusterShrunk = anyClusterShrunk || section.shrunk;
3471
5269
  chosenIndices.add(rc.idx);
3472
- projectedChars += sectionLen;
5270
+ projectedChars += text.length + GAP_MARKER.length;
3473
5271
  }
3474
5272
  // Emit chosen clusters in source order so the file reads top-to-bottom.
3475
- let fileSection = '';
3476
- const allSymbols = [];
3477
- for (let i = 0; i < clusters.length; i++) {
3478
- if (!chosenIndices.has(i))
3479
- continue;
3480
- const cluster = clusters[i];
3481
- const section = buildSection(cluster);
3482
- if (fileSection.length > 0)
3483
- fileSection += GAP_MARKER;
3484
- fileSection += section;
3485
- allSymbols.push(...cluster.symbols);
3486
- }
3487
- // A chosen cluster is a COMPLETE method-range — we never cut through a body.
3488
- // An oversize single cluster (a long monolithic function) renders in FULL:
3489
- // half a method is useless (the agent just Reads the rest for the other half),
3490
- // which is the very fallback explore exists to prevent. A pathological file is
3491
- // bounded by the per-file cluster SELECTION above + the total hard ceiling.
3492
- if (chosenIndices.size < clusters.length) {
5273
+ // Assembled through a function because it may have to run more than once:
5274
+ // the fit test below trims the weakest cluster and re-assembles rather
5275
+ // than skipping the file (CG-26).
5276
+ const assembleSection = (chosen) => {
5277
+ let text = '';
5278
+ const symbols = [];
5279
+ const ranges = [];
5280
+ const covered = [];
5281
+ for (let i = 0; i < clusters.length; i++) {
5282
+ if (!chosen.has(i))
5283
+ continue;
5284
+ const cluster = clusters[i];
5285
+ const section = renderedClusters.get(i);
5286
+ const part = sectionText(section.parts);
5287
+ if (part.length > 0) {
5288
+ if (text.length > 0)
5289
+ text += GAP_MARKER;
5290
+ text += part;
5291
+ }
5292
+ ranges.push(...section.parts.map((p) => p.range));
5293
+ covered.push(...section.covered);
5294
+ symbols.push(...cluster.symbols);
5295
+ }
5296
+ return { text, symbols, ranges, covered };
5297
+ };
5298
+ let assembled = assembleSection(chosenIndices);
5299
+ // A chosen cluster is a COMPLETE method-range — we never cut through a body,
5300
+ // and a shrunk cluster drops WHOLE members for the same reason. An oversize
5301
+ // single MEMBER (one long monolithic function) is kept whole for as long as
5302
+ // it fits the bounded overshoot (half a method is useless — the agent just
5303
+ // Reads the rest, the fallback explore exists to prevent); past that bound it
5304
+ // is WINDOWED on whole lines rather than dropped (CG-30), so a god-method
5305
+ // can neither be silently lost nor spend the response's whole envelope.
5306
+ if (chosenIndices.size < clusters.length || anyClusterShrunk) {
3493
5307
  anyFileTrimmed = true;
3494
5308
  }
3495
5309
  // Dedupe + cap the symbols list shown in the per-file header. Some
3496
5310
  // files (Session.swift in Alamofire) produced 3.4KB symbol lists
3497
5311
  // from cluster scoring + edge-source lines, dwarfing the per-file
3498
5312
  // body cap. Show top names by frequency, with a "+N more" tail.
3499
- const symbolCounts = new Map();
3500
- for (const s of allSymbols) {
3501
- symbolCounts.set(s, (symbolCounts.get(s) ?? 0) + 1);
3502
- }
3503
- const sortedSymbols = [...symbolCounts.entries()]
3504
- .sort((a, b) => b[1] - a[1])
3505
- .map(([name]) => name);
3506
- const headerCap = budget.maxSymbolsInFileHeader;
3507
- const headerSymbols = sortedSymbols.slice(0, headerCap);
3508
- const omittedCount = sortedSymbols.length - headerSymbols.length;
3509
- const headerSuffix = omittedCount > 0
3510
- ? `${headerSymbols.join(', ')}, +${omittedCount} more`
3511
- : headerSymbols.join(', ');
3512
- const fileHeader = fileSectionHeader(filePath, headerSuffix);
3513
- // The total cap bounds INCIDENTAL files only. A file that DEFINES a symbol
3514
- // the agent named (or that's on the flow spine) renders even when the
3515
- // nominal total is used up — it's the answer, and the set is bounded by
3516
- // maxFiles AND by true-spine/named-seeding having already trimmed each file
3517
- // to its necessary content. A file that merely REFERENCES the flow
3518
- // (Combine.swift name-drops request/task) is incidental → still capped, so
3519
- // freed budget never leaks into noise. This is the last god-file layer:
3520
- // build (Session, true-spined) + validators-exec (Request) + validate
3521
- // (DataRequest/Validation) all render, instead of the cap dropping whichever
3522
- // phase the file order happened to put last.
3523
- if (!fileNecessary && totalChars + fileSection.length + 200 > budget.maxOutputChars) {
3524
- // Incidental file that doesn't fit: SKIP it whole — never slice mid-method.
3525
- // Keep scanning for necessary files (which bypass this cap and render in
3526
- // full, bounded by the hard ceiling).
5313
+ const headerFor = (symbols) => {
5314
+ const symbolCounts = new Map();
5315
+ for (const s of symbols)
5316
+ symbolCounts.set(s, (symbolCounts.get(s) ?? 0) + 1);
5317
+ const sortedSymbols = [...symbolCounts.entries()]
5318
+ .sort((a, b) => b[1] - a[1])
5319
+ .map(([name]) => name);
5320
+ const headerSymbols = sortedSymbols.slice(0, budget.maxSymbolsInFileHeader);
5321
+ const omittedCount = sortedSymbols.length - headerSymbols.length;
5322
+ return fileSectionHeader(filePath, omittedCount > 0
5323
+ ? `${headerSymbols.join(', ')}, +${omittedCount} more`
5324
+ : headerSymbols.join(', '));
5325
+ };
5326
+ // Last stop before the hard ceiling. The reservation already bounded cluster
5327
+ // selection above, so reaching this means the bounded overshoot (an oversize
5328
+ // first cluster, taken whole rather than sliced mid-method) ran the response
5329
+ // out of room.
5330
+ //
5331
+ // Exact, like the whole-file arm above (CG-26): header + fences + body,
5332
+ // not body + a flat 200. The displacement half of the invariant is
5333
+ // already enforced on the body itself (`bodyCap` / `SPINE_CEILING` read
5334
+ // `fundedHeadroom`); this is the ceiling half. And because it is exact it
5335
+ // now bites at the margin — a header runs 300–500 chars where the body
5336
+ // budget assumed 200 — so an overrun TRIMS the weakest cluster and
5337
+ // re-assembles instead of skipping the file whole. Skipping a file over a
5338
+ // ~300-char accounting difference is starvation by rounding: the file was
5339
+ // admitted, reserved and rendered, and would have delivered nothing.
5340
+ // Only when the top-ranked cluster alone cannot fit is the file skipped —
5341
+ // that one is never sliced mid-method.
5342
+ let fileHeader = headerFor(assembled.symbols);
5343
+ let chosenNow = chosenIndices;
5344
+ const costOfSection = (header, body) => header.length + 2 + (body.length > 0 ? body.length + lang.length + 11 : 0);
5345
+ // The weakest cluster is SHRUNK into the room that is left before it is
5346
+ // dropped (CG-36). Dropping it whole makes this loop as all-or-nothing as
5347
+ // the selection above it was, and at the same cost: on excalidraw's
5348
+ // `typeChecks.ts` the estimate missed by 13 chars and a 1,512-char cluster
5349
+ // — the file's highest-SCORING one, last only because rank breaks ties on
5350
+ // density — was thrown away to pay for it. Below MIN_CHARS the remainder
5351
+ // cannot hold a readable block, and only then is the cluster dropped.
5352
+ const reshrunkOnce = new Set();
5353
+ while (totalChars + costOfSection(fileHeader, assembled.text) > renderCeiling
5354
+ && chosenNow.size > 1) {
5355
+ // Weakest first: `rankedClusters` is best-first, so walk it backwards.
5356
+ let weakest = -1;
5357
+ for (let i = rankedClusters.length - 1; i >= 0; i--) {
5358
+ const idx = rankedClusters[i].idx;
5359
+ if (chosenNow.has(idx)) {
5360
+ weakest = idx;
5361
+ break;
5362
+ }
5363
+ }
5364
+ if (weakest < 0)
5365
+ break;
5366
+ const over = totalChars + costOfSection(fileHeader, assembled.text) - renderCeiling;
5367
+ const current = renderedClusters.get(weakest);
5368
+ const currentLen = sectionText(current.parts).length;
5369
+ const room = currentLen - over;
5370
+ let reduced = false;
5371
+ // One attempt per cluster: a second pass means the first re-render did
5372
+ // not buy enough (the header moved with it), and the cluster is then
5373
+ // dropped rather than whittled a few chars at a time.
5374
+ if (room >= exports.EXPLORE_ALLOCATION.MIN_CHARS && !reshrunkOnce.has(weakest)) {
5375
+ reshrunkOnce.add(weakest);
5376
+ const reshrunk = renderCluster(clusters[weakest], room, room);
5377
+ const reshrunkLen = sectionText(reshrunk.parts).length;
5378
+ // Strictly smaller, or this loop cannot make progress and would spin.
5379
+ if (reshrunkLen > 0 && reshrunkLen < currentLen) {
5380
+ renderedClusters.set(weakest, reshrunk);
5381
+ anyClusterShrunk = true;
5382
+ reduced = true;
5383
+ }
5384
+ }
5385
+ if (!reduced) {
5386
+ const trimmed = new Set(chosenNow);
5387
+ trimmed.delete(weakest);
5388
+ chosenNow = trimmed;
5389
+ }
5390
+ assembled = assembleSection(chosenNow);
5391
+ fileHeader = headerFor(assembled.symbols);
3527
5392
  anyFileTrimmed = true;
5393
+ }
5394
+ // One cluster left and still over — by the header estimate's error, at
5395
+ // most a few hundred chars. Re-render it INTO the room that is actually
5396
+ // left rather than skip the file: the same whole-line windowing an
5397
+ // oversize cluster already gets (CG-30), just against an exact bound.
5398
+ // The header is built from the cluster's symbols, not its text, so
5399
+ // re-rendering cannot move the target.
5400
+ if (totalChars + costOfSection(fileHeader, assembled.text) > renderCeiling
5401
+ && chosenNow.size === 1) {
5402
+ const idx = [...chosenNow][0];
5403
+ const room = renderCeiling - totalChars
5404
+ - (fileHeader.length + 2 + lang.length + 11);
5405
+ if (room > 0) {
5406
+ const reshrunk = renderCluster(clusters[idx], room, room);
5407
+ renderedClusters.set(idx, reshrunk);
5408
+ anyClusterShrunk = anyClusterShrunk || reshrunk.shrunk;
5409
+ assembled = assembleSection(chosenNow);
5410
+ anyFileTrimmed = true;
5411
+ }
5412
+ }
5413
+ if (totalChars + costOfSection(fileHeader, assembled.text) > renderCeiling) {
5414
+ anyFileTrimmed = true;
5415
+ diag?.recordSkip(filePath, 'budget-clusters');
3528
5416
  continue;
3529
5417
  }
3530
- lines.push(fileHeader);
3531
- lines.push('');
3532
- lines.push('```' + lang);
3533
- lines.push(fileSection);
3534
- lines.push('```');
3535
- lines.push('');
3536
- totalChars += fileSection.length + 200;
3537
- renderedFilePaths.push(filePath);
3538
- filesIncluded++;
5418
+ const fileSection = assembled.text;
5419
+ const sectionRanges = assembled.ranges;
5420
+ const coveredRanges = assembled.covered;
5421
+ // The undeduped render of the same clusters, needed only if this file ends
5422
+ // up fully back-referenced AND the whole call finds nothing new to say —
5423
+ // see `suppressedFallback`. Built lazily: on every other call it is dead
5424
+ // weight.
5425
+ const fullClusterParts = fileSection.length === 0
5426
+ ? clusters.flatMap((c, i) => (chosenNow.has(i) ? buildSection(c) : []))
5427
+ : [];
5428
+ emitFileSection({
5429
+ header: fileHeader,
5430
+ body: fileSection,
5431
+ ranges: sectionRanges,
5432
+ covered: (0, explore_dedup_1.mergeRanges)(coveredRanges),
5433
+ overhead: 200,
5434
+ mode: 'clusters',
5435
+ // Windowing an oversize member elides source too — reporting it as
5436
+ // unclipped would hide exactly the cut the diagnostic exists to show.
5437
+ clipped: chosenNow.size < clusters.length || anyClusterShrunk,
5438
+ fullBody: sectionText(fullClusterParts),
5439
+ fullRanges: fullClusterParts.map((p) => p.range),
5440
+ });
5441
+ }
5442
+ // Anti-abandonment restore (CG-18). Dedup withheld everything and nothing new
5443
+ // took its place — the response would be pointers only, which is the shape
5444
+ // that reads as "codegraph found nothing" and sends the agent to Read for
5445
+ // good. Put the top suppressed file back, in full, and keep its pointer off.
5446
+ // Deliberately checked against `newSourceChars` (source THIS call emitted)
5447
+ // rather than the response length: the flow and blast-radius sections are
5448
+ // always there, and they are not what makes a response feel sufficient.
5449
+ // Cast, not annotation: the only writer is the render loop's `emitFileSection`
5450
+ // closure, which TypeScript's flow analysis cannot see, so it narrows the
5451
+ // variable to `null` here and the truthiness check below would be `never`.
5452
+ const restore = suppressedFallback;
5453
+ if (newSourceChars === 0 && restore) {
5454
+ if (totalChars + restore.sourceChars + restore.overhead <= renderCeiling) {
5455
+ lines.splice(restore.at, restore.replacing, ...restore.section);
5456
+ totalChars += restore.sourceChars + restore.overhead;
5457
+ sourceSpent += restore.sourceChars;
5458
+ newSourceChars += restore.sourceChars;
5459
+ filesIncluded++;
5460
+ const idx = backReferencedFiles.indexOf(restore.filePath);
5461
+ if (idx >= 0)
5462
+ backReferencedFiles.splice(idx, 1);
5463
+ emittedByFile.set(restore.filePath, {
5464
+ ranges: [...restore.ranges],
5465
+ bytes: restore.sourceChars,
5466
+ fingerprint: restore.fingerprint,
5467
+ });
5468
+ diag?.recordRender(restore.filePath, 'clusters', restore.sourceChars, false);
5469
+ diag?.recordDedup(restore.filePath, 0, []);
5470
+ }
3539
5471
  }
5472
+ // The back-reference convention, stated once where the verbatim guarantee is
5473
+ // (#1474 does the same for drift). Without it a pointer reads as an
5474
+ // apology for missing source rather than as an index into source the agent
5475
+ // already has.
5476
+ if (backReferencedFiles.length > 0) {
5477
+ lines[verbatimHeaderIdx] += ` (Files marked **"Already sent earlier in this conversation"** are not repeated: their source came back on an earlier codegraph_explore call in THIS conversation and the file has not changed since, so that copy is exact and current — scroll back for it rather than re-fetching or Reading.)`;
5478
+ }
5479
+ // Drift epilogue (#1474). The "verbatim / do not Read" guarantee above
5480
+ // stays TRUE for everything actually rendered (drifted files ship whole or
5481
+ // not at all — never as a possibly-wrong slice), but two caveats must be
5482
+ // explicit: omitted files need Reading, and index-derived LINE REFERENCES
5483
+ // to any drifted file (flow steps, blast radius, trail) may be shifted.
5484
+ if (staleOmitted.length > 0) {
5485
+ lines[verbatimHeaderIdx] += ' (Exception: files flagged "⚠ changed on disk" below drifted from the index after their last sync — their source is omitted rather than risk a mis-sliced block; Read those specific files.)';
5486
+ }
5487
+ const staleAll = [...new Set([...staleOmitted, ...staleRendered])];
5488
+ if (staleAll.length > 0) {
5489
+ lines.push('', `> ⚠ Changed on disk after the last index sync: ${staleAll.join(', ')}. Line numbers referencing ${staleAll.length === 1 ? 'this file' : 'these files'} elsewhere in this response (flow steps, blast radius, symbol lists) may be shifted until that project's next sync re-indexes ${staleAll.length === 1 ? 'it' : 'them'}.`);
5490
+ }
5491
+ // Everything pushed from here on is EPILOGUE — meta-text ABOUT the response
5492
+ // rather than part of it. Marked so the hard-ceiling cut at the end can
5493
+ // spend it before it spends a rendered file section (CG-31): a section is
5494
+ // source the agent otherwise has to Read; the epilogue is a pointer list and
5495
+ // two reminders, and the note that replaces it carries their instruction.
5496
+ //
5497
+ // Drawn AFTER the drift warning on purpose — that one is an honesty claim
5498
+ // about source we did render, not a note about the response, so it is never
5499
+ // the thing we drop. Lines already in `lines` are only MUTATED from here on
5500
+ // (the verbatim header, the summary sentinel), never re-ordered, so the
5501
+ // index stays valid.
5502
+ const epilogueStart = lines.length;
3540
5503
  // The curated header count is computed from the files that SURVIVE the final
3541
5504
  // truncation (see end of method) — `filesIncluded` can over-count when the
3542
5505
  // hard ceiling drops trailing sections — so leave a sentinel here and fill it
@@ -3544,64 +5507,136 @@ class ToolHandler {
3544
5507
  lines[summaryLineIdx] = SUMMARY_SENTINEL;
3545
5508
  // Add remaining files as references (from both relevant and peripheral files).
3546
5509
  // Small projects (per budget) skip this — the relevant story already fits
3547
- // in the source section, and a trailing pointer list is pure overhead.
3548
- if (budget.includeAdditionalFiles) {
3549
- const remainingRelevant = sortedFiles.slice(filesIncluded);
5510
+ // in the source section, and a trailing pointer list is pure overhead. But a
5511
+ // CLIFFED file is source we deliberately withheld, so the list is forced on
5512
+ // whenever there is one: withholding a file's bytes is only cheap if the agent
5513
+ // can still name it in a follow-up call (CG-12).
5514
+ // The epilogue's three blocks are BUILT here and FITTED below (CG-26) —
5515
+ // they are not pushed straight into `lines` any more. The render loop
5516
+ // budgets for the epilogue floor it committed to (`EPILOGUE_FLOOR`); what
5517
+ // the response can afford above that floor is only known now, so the
5518
+ // blocks are assembled against the room that actually remains, in priority
5519
+ // order, instead of being emitted whole and then discarded whole.
5520
+ const pointerEntries = [];
5521
+ let pointerOmitted = 0;
5522
+ if (budget.includeAdditionalFiles || cliffedFiles.size > 0) {
5523
+ // Everything ranked that didn't render, in rank order — cliffed files first,
5524
+ // since they outrank whatever the file cap cut. (Indexing by `filesIncluded`
5525
+ // would be wrong now that cliffed files are skipped without consuming a slot.)
5526
+ const rendered = new Set(renderedFilePaths);
5527
+ const remainingRelevant = sortedFiles.filter(([fp]) => !rendered.has(fp));
5528
+ // Ranked files are already covered by `remainingRelevant`; the rest of the
5529
+ // gather (below the floor) becomes the pointer list. The Set guards the
5530
+ // one overlap case — a file the SCORE_FLOOR_KEEP_MIN fallback pulled in
5531
+ // despite scoring under the relative floor.
5532
+ const rankedPaths = new Set(sortedFiles.map(([fp]) => fp));
3550
5533
  const peripheralFiles = [...fileGroups.entries()]
3551
- .filter(([, group]) => group.score < 3)
5534
+ .filter(([fp, group]) => group.score < scoreFloor && !rankedPaths.has(fp))
3552
5535
  .sort((a, b) => b[1].score - a[1].score);
3553
5536
  const remainingFiles = [...remainingRelevant, ...peripheralFiles];
3554
- if (remainingFiles.length > 0) {
3555
- lines.push('**Not shown above — explore these names for their source**');
3556
- lines.push('');
3557
- for (const [filePath, group] of remainingFiles.slice(0, 10)) {
3558
- const symbols = group.nodes.map(n => `${n.name}:${n.startLine}`).join(', ');
3559
- lines.push(`- ${filePath}: ${symbols}`);
3560
- }
3561
- if (remainingFiles.length > 10) {
3562
- lines.push(`- ... and ${remainingFiles.length - 10} more files`);
3563
- }
5537
+ for (const [filePath, group] of remainingFiles.slice(0, POINTER_MAX_FILES)) {
5538
+ pointerEntries.push(pointerLineFor(filePath, group.nodes));
3564
5539
  }
5540
+ pointerOmitted = Math.max(0, remainingFiles.length - pointerEntries.length);
3565
5541
  }
3566
- // Add completeness signal so agents know they don't need to re-read these files.
5542
+ // Completeness signal so agents know they don't need to re-read these files.
3567
5543
  // On small projects the budget gates this off — but if we actually had to
3568
5544
  // trim or drop clusters, surface a brief note so the agent knows it can
3569
5545
  // still Read for more detail.
3570
- if (budget.includeCompletenessSignal) {
3571
- lines.push('');
3572
- lines.push('---');
3573
- lines.push(`> **Complete source for ${filesIncluded} files is included above — do NOT re-read them.** If your question also needs files/symbols listed under "Not shown above" (or any area this call didn't cover), make ANOTHER codegraph_explore targeting those names — it returns the same source with line numbers and is cheaper and more complete than reading. Reserve Read for a single specific line range explore can't surface.`);
3574
- }
3575
- else if (anyFileTrimmed) {
3576
- lines.push('');
3577
- lines.push(`> Some file sections were trimmed for size. For a specific symbol you still need, run another \`codegraph_explore\` (or \`codegraph_node\`) with its exact name — line-numbered source, cheaper and more complete than Read.`);
3578
- }
3579
- // Add explore budget note based on project size
5546
+ const completenessBlock = budget.includeCompletenessSignal
5547
+ ? ['', '---', `> **Complete source for ${filesIncluded} files is included above — do NOT re-read them.** If your question also needs files/symbols listed under "Not shown above" (or any area this call didn't cover), make ANOTHER codegraph_explore targeting those names — it returns the same source with line numbers and is cheaper and more complete than reading. Reserve Read for a single specific line range explore can't surface.`]
5548
+ : anyFileTrimmed
5549
+ ? ['', `> Some file sections were trimmed for size. For a specific symbol you still need, run another \`codegraph_explore\` (or \`codegraph_node\`) with its exact name — line-numbered source, cheaper and more complete than Read.`]
5550
+ : [];
5551
+ // Explore budget note based on project size.
5552
+ let budgetBlock = [];
3580
5553
  if (budget.includeBudgetNote) {
3581
5554
  try {
3582
5555
  const stats = cg.getStats();
3583
5556
  const callBudget = getExploreBudget(stats.fileCount);
3584
- lines.push('');
3585
- lines.push(`> **Explore budget: ${callBudget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).** Each call covers ~6 files; if your question spans more, spend your remaining calls on the uncovered area BEFORE falling back to Read — another explore is cheaper and more complete than reading those files. Synthesize once you've used ${callBudget}.`);
5557
+ budgetBlock = ['', `> **Explore budget: ${callBudget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).** Each call covers ~6 files; if your question spans more, spend your remaining calls on the uncovered area BEFORE falling back to Read — another explore is cheaper and more complete than reading those files. Synthesize once you've used ${callBudget}.`];
3586
5558
  }
3587
5559
  catch {
3588
5560
  // Stats unavailable — skip budget note
3589
5561
  }
3590
5562
  }
3591
- // Final ceiling — an ABSOLUTE inline cap, not a multiple of the budget. The
3592
- // render loop renders necessary (named/spine) files even a bit past
3593
- // maxOutputChars and caps only incidental ones, so this is the last safety.
3594
- // It MUST stay under the host's inline tool-result limit (~25K chars): above
3595
- // that the result is externalized to a file the agent Reads back (a 35K
3596
- // vscode explore did exactly this in the n=4 A/B). So allow a little
3597
- // necessary overflow above the 24K budget, but hard-stop at 25K — never into
3598
- // externalize territory.
5563
+ // FIT THE EPILOGUE (CG-26). Before this, the epilogue was emitted whole and
5564
+ // then, on a saturated response, discarded whole by the hard ceiling — four
5565
+ // of six suite repos shipped with no pointer list and no reminders at all,
5566
+ // and the render loop had "budgeted" 600 chars for something that measures
5567
+ // 1,064–2,231. Neither number was the real one, because the epilogue is not
5568
+ // one thing: a fixed floor the loop reserves for (the cut note, plus a
5569
+ // pointer for every file whose bytes were deliberately WITHHELD — CG-12
5570
+ // makes those names load-bearing) and an elastic tail that takes what is
5571
+ // left. Assembled in priority order — the do-not-re-read reminder first,
5572
+ // then pointers in rank order, then the budget note — and emitted in
5573
+ // document order.
5574
+ const roomFor = (block) => block.reduce((n, s) => n + s.length + 1, 0);
5575
+ let room = hardCeiling - (flow.text.length + lines.join('\n').length);
5576
+ const keepCompleteness = completenessBlock.length > 0
5577
+ && roomFor(completenessBlock) <= room;
5578
+ if (keepCompleteness)
5579
+ room -= roomFor(completenessBlock);
5580
+ const pointerBlock = [];
5581
+ if (pointerEntries.length > 0) {
5582
+ const head = [POINTER_HEADER, ''];
5583
+ let left = room - roomFor(head);
5584
+ if (left >= 0) {
5585
+ let taken = 0;
5586
+ for (const entry of pointerEntries) {
5587
+ // Every entry we do NOT take has to be confessed by the tail line, so
5588
+ // the tail's cost is part of taking one less than all of them.
5589
+ const dropped = pointerEntries.length - taken - 1 + pointerOmitted;
5590
+ const tail = dropped > 0 ? roomFor([`- ... and ${dropped} more files`]) : 0;
5591
+ if (entry.length + 1 + tail > left)
5592
+ break;
5593
+ left -= entry.length + 1;
5594
+ taken++;
5595
+ }
5596
+ if (taken > 0) {
5597
+ pointerBlock.push(...head, ...pointerEntries.slice(0, taken));
5598
+ const dropped = pointerEntries.length - taken + pointerOmitted;
5599
+ if (dropped > 0)
5600
+ pointerBlock.push(`- ... and ${dropped} more files`);
5601
+ room -= roomFor(pointerBlock);
5602
+ }
5603
+ }
5604
+ }
5605
+ // Nothing of the pointer list survived, but there WAS one — say so, in the
5606
+ // one line that carries its instruction forward.
5607
+ const pointersLost = pointerEntries.length > 0 && pointerBlock.length === 0;
5608
+ const keepBudgetNote = budgetBlock.length > 0 && roomFor(budgetBlock) <= room;
5609
+ if (keepBudgetNote)
5610
+ room -= roomFor(budgetBlock);
5611
+ lines.push(...pointerBlock);
5612
+ if (keepCompleteness)
5613
+ lines.push(...completenessBlock);
5614
+ if (keepBudgetNote)
5615
+ lines.push(...budgetBlock);
5616
+ if (pointersLost && roomFor([EPILOGUE_LOST_NOTE, '']) <= room) {
5617
+ lines.push('', EPILOGUE_LOST_NOTE);
5618
+ }
3599
5619
  const output = flow.text + lines.join('\n');
3600
- const hardCeiling = Math.min(Math.round(budget.maxOutputChars * 1.5), 25000);
3601
5620
  let finalText;
3602
- if (output.length > hardCeiling) {
3603
- // Cut at a FILE-SECTION boundary (the last ``**` `` file header before the
3604
- // ceiling) so we drop whole trailing file-sections rather than slicing
5621
+ // The epilogue costs less than a file section, so it is cut FIRST (CG-31).
5622
+ // Dropping a trailing section throws away source the render loop had already
5623
+ // set that file's reservation aside for — the exact starvation the
5624
+ // displacement guard exists to prevent, arriving after the guard has done
5625
+ // its work. The epilogue is a pointer list and two reminders; its own
5626
+ // "explore these names" instruction survives in the note below.
5627
+ const epilogueOnlyCut = epilogueStart < lines.length
5628
+ ? flow.text + lines.slice(0, epilogueStart).join('\n')
5629
+ : null;
5630
+ const EPILOGUE_CUT_NOTE = '\n\n> (Trailing notes omitted for size. The source above is complete and verbatim — treat it as already Read. For anything this call did not cover, run another codegraph_explore with the specific names rather than reading those files.)';
5631
+ if (output.length > hardCeiling
5632
+ && epilogueOnlyCut !== null
5633
+ && epilogueOnlyCut.length + EPILOGUE_CUT_NOTE.length <= hardCeiling) {
5634
+ finalText = epilogueOnlyCut + EPILOGUE_CUT_NOTE;
5635
+ }
5636
+ else if (output.length > hardCeiling) {
5637
+ // Still over with the epilogue gone: cut at a FILE-SECTION boundary (the
5638
+ // last ``**` `` file header before the ceiling) so we drop whole trailing
5639
+ // file-sections rather than slicing
3605
5640
  // through a method body — a half-rendered method just forces the Read this
3606
5641
  // tool exists to prevent. Fall back to a line boundary only if no section
3607
5642
  // header sits in the back half (degenerate single-giant-section case).
@@ -3628,11 +5663,62 @@ class ToolHandler {
3628
5663
  return sum;
3629
5664
  return sum + new Set(g.nodes.filter((n) => n.kind !== 'import' && n.kind !== 'export').map((n) => n.id)).size;
3630
5665
  }, 0);
3631
- const summaryLine = survivors.length > 0
5666
+ let summaryLine = survivors.length > 0
3632
5667
  ? `Found ${shownSymbols} symbol${shownSymbols === 1 ? '' : 's'} across ${survivors.length} file${survivors.length === 1 ? '' : 's'}.`
3633
5668
  : `Found ${subgraph.nodes.size} symbol${subgraph.nodes.size === 1 ? '' : 's'} across ${fileGroups.size} file${fileGroups.size === 1 ? '' : 's'}.`;
5669
+ // Path pinning is visible, not silent: say which query-named files were
5670
+ // honored, and which path spans matched nothing so the agent can correct
5671
+ // them instead of trusting a response that quietly ignored the path.
5672
+ const pinnedShown = pinnedFiles.filter((fp) => survivors.includes(fp)).length;
5673
+ if (pinnedShown > 0) {
5674
+ summaryLine += ` ${pinnedShown} file${pinnedShown === 1 ? '' : 's'} pinned from the query.`;
5675
+ }
5676
+ if (unresolvedPathSpans.length > 0) {
5677
+ summaryLine += ` No indexed file uniquely matches ${unresolvedPathSpans.map((s) => `\`${s}\``).join(', ')}.`;
5678
+ }
3634
5679
  finalText = finalText.replace(SUMMARY_SENTINEL, summaryLine);
3635
- return this.textResult(finalText);
5680
+ // Emit the allocation diagnostic from the FINAL text, so per-file bytes and
5681
+ // shares account for the hard-ceiling truncation above (CG-4).
5682
+ diag?.finish(finalText, output.length, hardCeiling, filesIncluded);
5683
+ // Session record (CG-17): only the files that SURVIVED the hard ceiling —
5684
+ // a section the truncation dropped was never delivered, and recording it
5685
+ // would let a later call withhold source the agent has never seen.
5686
+ //
5687
+ // A back-referenced file records its spans at ZERO bytes (CG-18) — it is
5688
+ // still source the agent holds for this file, which is what the record
5689
+ // means; dropping it would let the span age out of the retained window and
5690
+ // be re-served for nothing.
5691
+ const emittedFiles = [];
5692
+ let sourceBytes = 0;
5693
+ for (const fp of survivors) {
5694
+ const emitted = emittedByFile.get(fp);
5695
+ if (!emitted || emitted.ranges.length === 0)
5696
+ continue;
5697
+ emittedFiles.push({
5698
+ path: fp,
5699
+ ranges: emitted.ranges,
5700
+ bytes: emitted.bytes,
5701
+ fingerprint: emitted.fingerprint,
5702
+ });
5703
+ sourceBytes += emitted.bytes;
5704
+ }
5705
+ return this.exploreResult(finalText, {
5706
+ projectRoot,
5707
+ query,
5708
+ files: emittedFiles,
5709
+ sourceBytes,
5710
+ responseBytes: finalText.length,
5711
+ });
5712
+ }
5713
+ /**
5714
+ * An explore response plus the record of what it emitted (CG-17). The record
5715
+ * rides the result only as far as {@link execute}, which files it into the
5716
+ * calling session's state and deletes it — see {@link EXPLORE_EMISSION_KEY}.
5717
+ */
5718
+ exploreResult(text, emission) {
5719
+ const result = this.textResult(text);
5720
+ result[explore_session_state_1.EXPLORE_EMISSION_KEY] = emission;
5721
+ return result;
3636
5722
  }
3637
5723
  /**
3638
5724
  * Handle codegraph_node
@@ -3879,6 +5965,14 @@ class ToolHandler {
3879
5965
  }
3880
5966
  /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
3881
5967
  async renderNodeSection(cg, node, includeCode) {
5968
+ // Disk-drift gate (issue #1474): the body below is CURRENT bytes sliced at
5969
+ // INDEXED line ranges. If the file changed since its last index sync, that
5970
+ // slice can be a DIFFERENT symbol's code served under this node's name —
5971
+ // confidently wrong, with no watcher banner to catch it on a `projectPath`
5972
+ // (cross-project) target. Never emit a slice from a drifted file.
5973
+ if (this.isFileStaleOnDisk(cg, node.filePath)) {
5974
+ return this.renderStaleNodeSection(cg, node, includeCode);
5975
+ }
3882
5976
  let code = null;
3883
5977
  let outline = null;
3884
5978
  if (includeCode) {
@@ -3895,6 +5989,55 @@ class ToolHandler {
3895
5989
  }
3896
5990
  return this.formatNodeDetails(node, code, outline) + this.formatTrail(cg, node);
3897
5991
  }
5992
+ // Whole-file fallback caps for a drifted file (#1474): small enough to fit
5993
+ // codegraph_node's output cap (MAX_OUTPUT_LENGTH) with headroom for the
5994
+ // header + trail. A file within these bounds is served WHOLE and CURRENT
5995
+ // (Read-parity, correct by construction) instead of a possibly-wrong slice.
5996
+ static STALE_WHOLE_FILE_MAX_LINES = 300;
5997
+ static STALE_WHOLE_FILE_MAX_CHARS = 12000;
5998
+ /**
5999
+ * codegraph_node render for a symbol whose file changed on disk after the
6000
+ * last index sync (issue #1474). The indexed line range is no longer
6001
+ * trustworthy, so no slice is emitted: a small file gets its full CURRENT
6002
+ * source (Read-parity — sufficiency preserved, the agent still doesn't need
6003
+ * Read); a large one gets an explicit notice steering to the tool's own
6004
+ * file-read mode (or Read) — honest absence instead of confident wrongness.
6005
+ * Location/signature stay (they're the index's answer) but are flagged as
6006
+ * possibly shifted.
6007
+ */
6008
+ renderStaleNodeSection(cg, node, includeCode) {
6009
+ const lines = [
6010
+ `**${node.name}** (${node.kind})`,
6011
+ '',
6012
+ `**Location:** ${node.filePath}${node.startLine ? `:${node.startLine}` : ''} — ⚠ as of the last index sync; the file has changed on disk since, so this line may be shifted`,
6013
+ ];
6014
+ if (node.signature) {
6015
+ lines.push(`**Signature:** \`${node.signature}\``);
6016
+ }
6017
+ lines.push('');
6018
+ let embedded = false;
6019
+ if (includeCode) {
6020
+ try {
6021
+ const absPath = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), node.filePath);
6022
+ if (absPath && (0, fs_1.existsSync)(absPath) && !(0, utils_1.isConfigLeafNode)(node)) {
6023
+ const content = (0, fs_1.readFileSync)(absPath, 'utf-8');
6024
+ const body = content.replace(/\n+$/, '');
6025
+ if (body.length <= ToolHandler.STALE_WHOLE_FILE_MAX_CHARS &&
6026
+ body.split('\n').length <= ToolHandler.STALE_WHOLE_FILE_MAX_LINES) {
6027
+ lines.push(`> ⚠ \`${node.filePath}\` changed on disk after it was last indexed, so the indexed line range for this symbol may no longer match. Showing the file's full CURRENT source instead (Read-parity — treat it as already Read):`, '', '```' + (node.language || ''), numberSourceLines(body, 1), '```');
6028
+ embedded = true;
6029
+ }
6030
+ }
6031
+ }
6032
+ catch {
6033
+ /* fall through to the notice */
6034
+ }
6035
+ }
6036
+ if (!embedded) {
6037
+ lines.push(`> ⚠ \`${node.filePath}\` changed on disk after it was last indexed — the indexed line range for this symbol no longer reliably matches, so its body is omitted rather than risk showing a different symbol's code. For current content, call codegraph_node with \`file: "${node.filePath}"\` (no symbol; \`offset\`/\`limit\` narrow it like Read), or Read the file. The change is picked up automatically on that project's next index sync.`);
6038
+ }
6039
+ return lines.join('\n') + this.formatTrail(cg, node);
6040
+ }
3898
6041
  /**
3899
6042
  * Build the "trail" for a symbol: its direct callees (what it calls) and
3900
6043
  * callers (what calls it), each with file:line — so codegraph_node doubles as
@@ -4222,6 +6365,20 @@ class ToolHandler {
4222
6365
  * Python — `stage_apply::run` matches a `run` in `stage_apply.rs`)
4223
6366
  */
4224
6367
  matchesSymbol(node, symbol) {
6368
+ // Erlang arity spelling (`fn/3`, `mod:fn/3` → normalized `mod.fn/3`): when
6369
+ // the node's qualifiedName carries an arity (`mod::fn/3`, #1610), the
6370
+ // written arity must match it exactly; the remaining comparison then runs
6371
+ // on the arity-less spelling. A node with no arity in its qualifiedName
6372
+ // keeps the original symbol (a `/` there means a path-ish name instead).
6373
+ const aritySpelling = /^(.+)\/(\d{1,3})$/.exec(symbol);
6374
+ if (aritySpelling) {
6375
+ const nodeArity = /\/(\d{1,3})$/.exec(node.qualifiedName ?? '')?.[1];
6376
+ if (nodeArity !== undefined) {
6377
+ if (nodeArity !== aritySpelling[2])
6378
+ return false;
6379
+ symbol = aritySpelling[1];
6380
+ }
6381
+ }
4225
6382
  // Simple name match
4226
6383
  if (node.name === symbol)
4227
6384
  return true;
@@ -4276,7 +6433,8 @@ class ToolHandler {
4276
6433
  if (!isQualified) {
4277
6434
  const exact = cg.getNodesByName(symbol);
4278
6435
  if (exact.length > 0) {
4279
- return [...exact].sort((a, b) => ((0, generated_detection_1.isGeneratedFile)(a.filePath) ? 1 : 0) - ((0, generated_detection_1.isGeneratedFile)(b.filePath) ? 1 : 0));
6436
+ const isGen = cg.generatedFilePredicate(exact.map((n) => n.filePath));
6437
+ return [...exact].sort((a, b) => (isGen(a.filePath) ? 1 : 0) - (isGen(b.filePath) ? 1 : 0));
4280
6438
  }
4281
6439
  // No exact match — use the single top fuzzy result (e.g. a file basename).
4282
6440
  const fuzzy = cg.searchNodes(symbol, { limit: 10 });
@@ -4301,10 +6459,12 @@ class ToolHandler {
4301
6459
  // hit (#173); a bare name may use the single top fuzzy result.
4302
6460
  return isQualified ? [] : results[0] ? [results[0].node] : [];
4303
6461
  }
4304
- // Down-rank generated files (.pb.go, .pulsar.go, _grpc.pb.go, …) so a flow
4305
- // query prefers the keeper implementation over the protobuf-generated stub.
6462
+ // Down-rank generated files (.pb.go, .pulsar.go, _grpc.pb.go, and anything
6463
+ // whose header declares it generated) so a flow query prefers the keeper
6464
+ // implementation over the generated stub.
6465
+ const isGen = cg.generatedFilePredicate(exactMatches.map((r) => r.node.filePath));
4306
6466
  return [...exactMatches]
4307
- .sort((a, b) => ((0, generated_detection_1.isGeneratedFile)(a.node.filePath) ? 1 : 0) - ((0, generated_detection_1.isGeneratedFile)(b.node.filePath) ? 1 : 0))
6467
+ .sort((a, b) => (isGen(a.node.filePath) ? 1 : 0) - (isGen(b.node.filePath) ? 1 : 0))
4308
6468
  .map((r) => r.node);
4309
6469
  }
4310
6470
  /**
@@ -4352,9 +6512,10 @@ class ToolHandler {
4352
6512
  // Same generated-file down-rank as findSymbol — keeps callers/callees
4353
6513
  // /impact aggregation aligned (a query against "Send" returns the
4354
6514
  // hand-written implementations before the protobuf scaffold).
6515
+ const isGen = cg.generatedFilePredicate(exactMatches.map((r) => r.node.filePath));
4355
6516
  const ranked = [...exactMatches].sort((a, b) => {
4356
- const aGen = (0, generated_detection_1.isGeneratedFile)(a.node.filePath) ? 1 : 0;
4357
- const bGen = (0, generated_detection_1.isGeneratedFile)(b.node.filePath) ? 1 : 0;
6517
+ const aGen = isGen(a.node.filePath) ? 1 : 0;
6518
+ const bGen = isGen(b.node.filePath) ? 1 : 0;
4358
6519
  return aGen - bGen;
4359
6520
  });
4360
6521
  const locations = ranked.map(r => `${r.node.kind} at ${r.node.filePath}:${r.node.startLine}`);