From f2a5df34de99c46c70a889fc6c8852c886133134 Mon Sep 17 00:00:00 2001 From: Colby Mchenry Date: Sat, 1 Aug 2026 01:12:52 -0500 Subject: [PATCH] fix(mcp): never serve a mis-sliced symbol body from a file that drifted from its index (#1474) (#1492) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit codegraph_node / codegraph_explore read CURRENT bytes but slice them at INDEXED line ranges; after an un-synced edit that slice can be a DIFFERENT symbol's code served under the requested name — isError: false, introduced by the 'verbatim … do not Read' guarantee. The watcher-based pending (#403) and degraded (#876) banners cannot cover a project reached via projectPath: cross-project instances have no watcher, by construction. Freshness is now verified at the point of emission from data the index already stores: one stat per rendered file (size + floored mtime, the sync fast path's own test), sha256 content-hash compare only on stat mismatch (so a touch/identical rewrite never false-positives), memoized briefly per handler. On drift: - codegraph_node: small files ship WHOLE and CURRENT (Read-parity, still no Read needed); large ones omit the body with an explicit notice steering to the tool's file-read mode or Read. Location/signature stay, flagged as possibly shifted. - codegraph_explore: the whole-file render (already correct by construction) is kept and flagged; adaptive/skeleton/cluster slicing is disabled for drifted files — a too-big drifted file is omitted with a notice instead. The verbatim/do-not-Read header gains a per-file exception, and a trailing note flags shifted line references (flow, blast radius, symbol lists). The guarantee itself is preserved: everything actually rendered is still byte-accurate — drifted files ship whole or not at all, never as a possibly-wrong slice. A re-sync of the target project restores normal output (covered by test). Adds __setLoadCodeGraphForTests (same seam pattern as __setFsWatchForTests) so in-process tests can exercise a genuine cross-project open, which vitest's transform cannot service through the lazy require. Co-authored-by: Claude Fable 5 --- CHANGELOG.md | 1 + __tests__/mcp-stale-slice.test.ts | 221 ++++++++++++++++++++++++++++++ src/mcp/server-instructions.ts | 1 + src/mcp/tools.ts | 198 +++++++++++++++++++++++++- 4 files changed, 418 insertions(+), 3 deletions(-) create mode 100644 __tests__/mcp-stale-slice.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 951673c..b36a9dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - The background server's watchdog no longer kills a healthy server that is just waiting on a slow disk: like indexing already does, it now checks whether the database files are still making progress before concluding the process is stuck. Fewer spurious kills also means fewer leftover write-ahead logs. (#1431) - `codegraph status` now shows the write-ahead log's size next to the database size and warns when killed sessions have left it oversized, and every line in the background server's log now carries a timestamp so kills and restarts can be placed in time. (#1431) - On Windows, the Claude Code prompt hook written by `codegraph install` failed with "command not found" when hooks run through Git Bash, which needs the `.cmd` extension to find the launcher. The installer now writes the platform-correct command, and re-running `codegraph install` (or `codegraph upgrade`) repairs an existing install in place. (#1466) +- When a file changed on disk after its last index sync, `codegraph_node` and `codegraph_explore` could return a different symbol's code under the requested name — current file bytes cut at outdated line positions — while presenting it as verbatim, trustworthy source. This hit hardest on projects queried through `projectPath` (for example, sub-projects of a monorepo), which have no live file watcher to flag pending edits. Both tools now verify each file against the index before showing sliced code: an out-of-date file is either shown whole with its full current source, or its code is withheld with a clear "changed on disk" notice — never served as a wrong slice. A fresh re-index restores normal output automatically. Thanks @inth3shadows for the thorough report and verification passes. (#1474) ## [1.5.0] - 2026-07-21 diff --git a/__tests__/mcp-stale-slice.test.ts b/__tests__/mcp-stale-slice.test.ts new file mode 100644 index 0000000..bc550cc --- /dev/null +++ b/__tests__/mcp-stale-slice.test.ts @@ -0,0 +1,221 @@ +/** + * Disk-drift guard on code-slice renders (issue #1474). + * + * codegraph_node / codegraph_explore read CURRENT bytes from disk but slice + * them at INDEXED line ranges. When a file changed after its last index sync, + * that slice is a DIFFERENT symbol's code served under the requested name — + * `isError: false`, introduced by the "verbatim … do not Read" guarantee. The + * watcher-based pending banner (#403) cannot cover a project reached via + * `projectPath` (cross-project instances have no watcher, by construction). + * + * The fix verifies freshness at the point of emission from data the index + * already stores (files.size / modified_at, content_hash on stat mismatch): + * a drifted file is never rendered as a slice — small files ship whole and + * current (Read-parity), large ones are omitted with an explicit notice. + * + * These tests exercise the full real path: real index + real + * ToolHandler.execute(), including the cross-project `projectPath` form the + * issue was filed against. + */ + +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import * as fs from 'fs'; +import * as path from 'path'; +import * as os from 'os'; +import CodeGraph from '../src/index'; +import { ToolHandler, __setLoadCodeGraphForTests } from '../src/mcp/tools'; + +/** ~1,100-line file: handler0…handler79 plus `orchestrate` at the bottom — + * mirrors the issue's fixture. Big enough that explore takes the clustered + * render and codegraph_node's whole-file stale fallback does NOT fit. */ +function bigFileContent(): string { + const parts: string[] = []; + for (let h = 0; h < 80; h++) { + parts.push(`/** handler number ${h} */`); + parts.push(`export function handler${h}(input: string): string {`); + for (let s = 0; s < 8; s++) { + parts.push(` const v${s} = input + "-step${s}-h${h}";`); + } + parts.push(` return v7;`); + parts.push(`}`); + parts.push(''); + } + parts.push(`export function orchestrate(input: string): string {`); + parts.push(` handler0(input);`); + parts.push(` handler1(input);`); + parts.push(` handler2(input);`); + parts.push(` handler3(input);`); + parts.push(` return input;`); + parts.push(`}`); + parts.push(''); + return parts.join('\n'); +} + +/** 45 lines of new helpers inserted at the top — shifts every symbol down. */ +function insertedPrelude(): string { + const parts: string[] = []; + for (let h = 0; h < 4; h++) { + parts.push(`/** inserted helper ${h} */`); + parts.push(`export function insertedHelper${h}(x: number): number {`); + for (let s = 0; s < 7; s++) { + parts.push(` x = x + ${s};`); + } + parts.push(` return x;`); + parts.push(`}`); + } + parts.push(''); + return parts.join('\n') + '\n'; +} + +function getText(result: { content: Array<{ type: string; text?: string }>; isError?: boolean }): string { + return result.content.map((c) => c.text ?? '').join('\n'); +} + +describe('MCP stale-slice guard (#1474)', () => { + let fixtureDir: string; // the project that goes stale + let otherDir: string; // a different indexed project — the server's default + let cgFixture: CodeGraph; + let cgOther: CodeGraph; + let handler: ToolHandler; + + beforeEach(async () => { + fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-stale-slice-fx-')); + otherDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-stale-slice-other-')); + fs.mkdirSync(path.join(fixtureDir, 'src')); + fs.mkdirSync(path.join(otherDir, 'src')); + fs.writeFileSync(path.join(fixtureDir, 'src', 'big.ts'), bigFileContent()); + fs.writeFileSync( + path.join(fixtureDir, 'src', 'small.ts'), + 'export function smallTarget(n: number): number {\n return n * 2;\n}\n', + ); + fs.writeFileSync( + path.join(otherDir, 'src', 'unrelated.ts'), + 'export function unrelated() { return 0; }\n', + ); + + cgFixture = CodeGraph.initSync(fixtureDir, { config: { include: ['**/*.ts'], exclude: [] } }); + await cgFixture.indexAll(); + cgOther = CodeGraph.initSync(otherDir, { config: { include: ['**/*.ts'], exclude: [] } }); + await cgOther.indexAll(); + // The issue's exact topology: the server's default project is a DIFFERENT + // project; the stale one is reached via `projectPath` and therefore has no + // watcher — the #403/#876 banners cannot fire for it by construction. + // (The seam services ToolHandler's lazy cross-project require, which + // vitest's module transform can't resolve.) + __setLoadCodeGraphForTests(CodeGraph); + handler = new ToolHandler(cgOther); + }); + + afterEach(() => { + __setLoadCodeGraphForTests(null); + try { handler.closeAll(); } catch { /* ignore */ } + try { cgFixture.close(); } catch { /* ignore */ } + try { cgOther.close(); } catch { /* ignore */ } + for (const dir of [fixtureDir, otherDir]) { + if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true }); + } + }); + + function shiftBigFile(): void { + const p = path.join(fixtureDir, 'src', 'big.ts'); + fs.writeFileSync(p, insertedPrelude() + fs.readFileSync(p, 'utf-8')); + } + + it('codegraph_node never serves another symbol\'s body from a drifted file (cross-project)', async () => { + shiftBigFile(); + const result = await handler.execute('codegraph_node', { + symbol: 'orchestrate', + includeCode: true, + projectPath: fixtureDir, + }); + const text = getText(result); + expect(result.isError).toBeFalsy(); + // The pre-fix failure: the indexed range now lands in handler76/handler77. + expect(text).not.toContain('-h76'); + expect(text).not.toContain('handler77'); + // The drift is announced and the agent is pointed at trustworthy reads. + expect(text).toContain('changed on disk after it was last indexed'); + expect(text).toContain('orchestrate'); + }); + + it('codegraph_node serves the full CURRENT source of a small drifted file (Read-parity fallback)', async () => { + const p = path.join(fixtureDir, 'src', 'small.ts'); + fs.writeFileSync(p, '/** new first line */\nexport const shift = 1;\n' + fs.readFileSync(p, 'utf-8')); + const result = await handler.execute('codegraph_node', { + symbol: 'smallTarget', + includeCode: true, + projectPath: fixtureDir, + }); + const text = getText(result); + expect(result.isError).toBeFalsy(); + expect(text).toContain('full CURRENT source'); + // Current content, including the just-inserted lines the index knows nothing about. + expect(text).toContain('new first line'); + expect(text).toContain('smallTarget'); + }); + + it('an identical rewrite (mtime churn, same bytes) does not trip the guard', async () => { + const p = path.join(fixtureDir, 'src', 'big.ts'); + fs.writeFileSync(p, fs.readFileSync(p, 'utf-8')); + const result = await handler.execute('codegraph_node', { + symbol: 'orchestrate', + includeCode: true, + projectPath: fixtureDir, + }); + const text = getText(result); + expect(text).not.toContain('changed on disk'); + expect(text).toContain('export function orchestrate'); + }); + + it('codegraph_explore omits (never mis-slices) a big drifted file and flags line refs', async () => { + shiftBigFile(); + const result = await handler.execute('codegraph_explore', { + query: 'orchestrate handler3', + projectPath: fixtureDir, + }); + const text = getText(result); + expect(result.isError).toBeFalsy(); + expect(text).toContain('changed on disk after the last index sync'); + // No sliced body from the drifted file — its step lines must not appear. + expect(text).not.toMatch(/-step\d-h\d/); + // Line-reference caveat for the drifted file. + expect(text).toContain('may be shifted'); + }); + + it('re-syncing the project restores normal output with no drift markers', async () => { + shiftBigFile(); + await cgFixture.sync(); + // Fresh handler: the drift verdict is briefly memoized per handler. + const freshHandler = new ToolHandler(cgOther); + try { + const result = await freshHandler.execute('codegraph_node', { + symbol: 'orchestrate', + includeCode: true, + projectPath: fixtureDir, + }); + const text = getText(result); + expect(text).not.toContain('changed on disk'); + expect(text).toContain('export function orchestrate'); + // Location reflects the post-shift position (45 inserted lines). + expect(text).toMatch(/Location:\*\* src\/big\.ts:\d+/); + } finally { + try { freshHandler.closeAll(); } catch { /* ignore */ } + } + }); + + it('the guard also fires on the default project when no watcher is running', async () => { + shiftBigFile(); + const direct = new ToolHandler(cgFixture); + try { + const result = await direct.execute('codegraph_node', { + symbol: 'orchestrate', + includeCode: true, + }); + const text = getText(result); + expect(text).not.toContain('handler77'); + expect(text).toContain('changed on disk after it was last indexed'); + } finally { + try { direct.closeAll(); } catch { /* ignore */ } + } + }); +}); diff --git a/src/mcp/server-instructions.ts b/src/mcp/server-instructions.ts index 88f6f2e..bf3839a 100644 --- a/src/mcp/server-instructions.ts +++ b/src/mcp/server-instructions.ts @@ -60,6 +60,7 @@ calls; a grep/read exploration is dozens. - **Don't grep or Read first** to find or understand indexed code — ONE \`codegraph_explore\` returns the relevant symbols' source together in a single round-trip. Reach for raw \`Read\`/\`Grep\` only to confirm a specific detail codegraph didn't cover, or for what codegraph doesn't index (configs, docs). - **Don't reconstruct a flow by hand** — name the endpoints in one \`codegraph_explore\` and it surfaces the path between them, dynamic-dispatch hops included. - **After editing, check the staleness banner.** When a tool response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. A different, rarer banner — "⚠️ CodeGraph auto-sync is DISABLED…" — means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed. +- **A file flagged "⚠ changed on disk after the last index sync" drifted from its index** (most common on projects queried via \`projectPath\`, which have no live watcher). Codegraph never serves a possibly-mis-sliced body from such a file — it either shows the file's full CURRENT source (trust it as a Read) or omits the source with this flag. When the source was omitted, Read that specific file; line numbers referencing it elsewhere in the response may be shifted until that project's next sync. All unflagged files remain trustworthy. ## Limitations diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts index b31c64f..3995ab3 100644 --- a/src/mcp/tools.ts +++ b/src/mcp/tools.ts @@ -13,7 +13,16 @@ import { findNearestCodeGraphRoot } from '../directory'; // CodeGraph is pulled in only when a tool actually opens a project. require() is // sync + cached (CommonJS build). const loadCodeGraph = (): typeof import('../index').default => - (require('../index') as typeof import('../index')).default; + loadCodeGraphForTests ?? (require('../index') as typeof import('../index')).default; +// Test seam (same pattern as the watcher's `__setFsWatchForTests`): vitest's +// module transform can't service the lazy `require('../index')` above, so +// in-process tests that exercise a genuine cross-project open (an explicit +// `projectPath` to a different project — issue #1474's repro shape) inject the +// already-imported class here. Never set outside tests. +let loadCodeGraphForTests: typeof import('../index').default | null = null; +export function __setLoadCodeGraphForTests(cls: typeof import('../index').default | null): void { + loadCodeGraphForTests = cls; +} import { detectWorktreeIndexMismatch, worktreeMismatchWarning, @@ -26,7 +35,9 @@ import { isTestFile, normalizeNameToken } from '../search/query-utils'; import { existsSync, readFileSync, + statSync, } from 'fs'; +import { createHash } from 'crypto'; import { clamp, validatePathWithinRoot, validateProjectPath, isConfigLeafNode, CONFIG_LEAF_LANGUAGES } from '../utils'; import { isGeneratedFile } from '../extraction/generated-detection'; import { scanDynamicDispatch } from './dynamic-boundaries'; @@ -1257,6 +1268,67 @@ export class ToolHandler { * Cost when nothing is pending — the common case — is one boolean check. * No I/O, no parsing of markdown beyond a per-pending-file substring scan. */ + private driftCache = new Map(); + private static readonly DRIFT_TTL_MS = 2000; + + /** + * On-disk drift check for a single indexed file (issue #1474). The code + * renderers slice CURRENT bytes at INDEXED line ranges; when the file + * changed after its last index sync those ranges can point at a DIFFERENT + * symbol's code — served under the requested name with `isError: false`. + * The watcher-based pending/degraded banners can't cover this for a + * project reached via `projectPath` (cross-project instances have no + * watcher, by construction), so freshness is verified here, at the point + * of emission, from data the index already stores. + * + * Cheap and precise: one stat() per file (size + mtime, the same + * comparison the sync fast path uses); only on a stat mismatch is the + * content hashed (sha256, matching extraction's `hashContent`) so a + * touch/checkout that rewrote identical bytes never false-positives. + * Results are memoized briefly so one response rendering the same file in + * several sections pays for the check once. + * + * Returns true when the on-disk file differs from what was indexed — + * i.e. indexed line ranges for it are NOT trustworthy. Any failure + * (missing files-table row, stat/read error) reports false: those cases + * are handled by the existing not-found paths, and a wrong "stale" flag + * would needlessly push the agent back to Read. + */ + private isFileStaleOnDisk(cg: CodeGraph, relPath: string, content?: string): boolean { + let root: string; + try { + root = cg.getProjectRoot(); + } catch { + return false; + } + const key = `${root}\0${relPath}`; + const now = Date.now(); + const hit = this.driftCache.get(key); + if (hit && now - hit.at < ToolHandler.DRIFT_TTL_MS) return hit.stale; + let stale = false; + try { + const rec = cg.getFile(relPath); + const absPath = rec ? validatePathWithinRoot(root, relPath) : null; + if (rec && absPath && existsSync(absPath)) { + const st = statSync(absPath); + // Same freshness test as the sync fast path (extraction/index.ts): + // equal size + equal floored mtime ⇒ unchanged, no read needed. + if (st.size !== rec.size || Math.floor(st.mtimeMs) !== Math.floor(rec.modifiedAt)) { + const data = content ?? readFileSync(absPath, 'utf-8'); + // Must stay byte-identical to extraction's `hashContent` (sha256 over + // the utf-8 string) — the identical-rewrite test in + // mcp-stale-slice.test.ts pins the parity. Inlined (not imported) + // to keep the extraction module off the MCP startup path. + stale = createHash('sha256').update(data).digest('hex') !== rec.contentHash; + } + } + } catch { + stale = false; + } + this.driftCache.set(key, { at: now, stale }); + return stale; + } + private withStalenessNotice(result: ToolResult, projectPath?: string): ToolResult { if (result.isError) return result; @@ -3139,6 +3211,9 @@ export class ToolHandler { lines.push('**Source Code**'); lines.push(''); + // Recorded so the drift pass below (#1474) can append a per-file exception + // to this guarantee after the render loop knows which files drifted. + const verbatimHeaderIdx = lines.length; 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.'); lines.push(''); @@ -3148,6 +3223,14 @@ export class ToolHandler { // (#1046) — it must reflect what we show, not the raw candidate gather. const renderedFilePaths: string[] = []; let anyFileTrimmed = false; + // Files that changed on disk after their last index sync (#1474). Their + // indexed line ranges are untrustworthy, so sliced renders (adaptive / + // skeleton / clusters) are OFF for them: a small drifted file still ships + // whole (current bytes, correct by construction → staleRendered), a big one + // is omitted with an explicit notice (→ staleOmitted) — honest absence + // instead of a different symbol's code under the requested name. + const staleRendered: string[] = []; + const staleOmitted: string[] = []; for (const [filePath, group] of sortedFiles) { if (filesIncluded >= maxFiles) break; @@ -3174,6 +3257,11 @@ export class ToolHandler { const fileLines = fileContent.split('\n'); const lang = group.nodes[0]?.language || ''; + // Disk-drift gate (#1474): every render branch below except whole-file + // slices fileContent (CURRENT bytes) at INDEXED line ranges. Content is + // already in hand, so the check costs one stat (hash only on mismatch). + const fileStale = this.isFileStaleOnDisk(cg, filePath, fileContent); + // Adaptive sizing (CODEGRAPH_ADAPTIVE_EXPLORE, default on): collapse a file // to a per-symbol view when it's a redundant member of a polymorphic family. // Engages iff ALL hold: @@ -3212,7 +3300,7 @@ export class ToolHandler { const onSpineGodFile = hasSpineNode && namedBodyChars > budget.maxCharsPerFile && group.nodes.some(n => CALLABLE_BODY.has(n.kind) && flow.uniqueNamedNodeIds.has(n.id) && !flow.pathNodeIds.has(n.id)); - if (adaptiveExploreEnabled() && flow.pathNodeIds.size > 0 + if (!fileStale && adaptiveExploreEnabled() && flow.pathNodeIds.size > 0 && (onSpineGodFile || (!hasSpineNode && isPolymorphicSibling(group.nodes) && !spared))) { const syms = group.nodes .filter(n => n.kind !== 'import' && n.kind !== 'export' && n.startLine > 0) @@ -3326,7 +3414,11 @@ export class ToolHandler { )]; const headerNames = uniqSymbols.slice(0, budget.maxSymbolsInFileHeader); const omitted = uniqSymbols.length - headerNames.length; - const wholeHeader = fileSectionHeader(filePath, omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', ')); + // A drifted file rendered WHOLE is still correct (current bytes, + // numbered from 1) — only the index-derived symbol list / line refs to + // it elsewhere in this response may be shifted (#1474). Flag that. + const staleSuffix = fileStale ? ' · ⚠ changed since last index sync — source below is current; the symbol list may be outdated' : ''; + const wholeHeader = fileSectionHeader(filePath, (omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', ')) + staleSuffix); if (!fileNecessary && totalChars + wholeSection.length + 200 > budget.maxOutputChars) { // Don't slice a whole file mid-method: an incidental file that doesn't @@ -3339,6 +3431,22 @@ export class ToolHandler { totalChars += wholeSection.length + 200; renderedFilePaths.push(filePath); filesIncluded++; + if (fileStale) staleRendered.push(filePath); + continue; + } + + // Drifted file too big for the whole-file window (#1474): the cluster / + // skeleton renders below would slice current bytes at indexed ranges — + // on a shifted file that serves a DIFFERENT symbol's code under the + // requested name. Omit the source with an explicit notice instead; + // never render a possibly-wrong slice. + if (fileStale) { + staleOmitted.push(filePath); + lines.push( + 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.'), + '', + ); + totalChars += 260; continue; } @@ -3626,6 +3734,22 @@ export class ToolHandler { filesIncluded++; } + // Drift epilogue (#1474). The "verbatim / do not Read" guarantee above + // stays TRUE for everything actually rendered (drifted files ship whole or + // not at all — never as a possibly-wrong slice), but two caveats must be + // explicit: omitted files need Reading, and index-derived LINE REFERENCES + // to any drifted file (flow steps, blast radius, trail) may be shifted. + if (staleOmitted.length > 0) { + 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.)'; + } + const staleAll = [...new Set([...staleOmitted, ...staleRendered])]; + if (staleAll.length > 0) { + 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'}.`, + ); + } + // The curated header count is computed from the files that SURVIVE the final // truncation (see end of method) — `filesIncluded` can over-count when the // hard ceiling drops trailing sections — so leave a sentinel here and fill it @@ -3994,6 +4118,14 @@ export class ToolHandler { /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */ private async renderNodeSection(cg: CodeGraph, node: Node, includeCode: boolean): Promise { + // Disk-drift gate (issue #1474): the body below is CURRENT bytes sliced at + // INDEXED line ranges. If the file changed since its last index sync, that + // slice can be a DIFFERENT symbol's code served under this node's name — + // confidently wrong, with no watcher banner to catch it on a `projectPath` + // (cross-project) target. Never emit a slice from a drifted file. + if (this.isFileStaleOnDisk(cg, node.filePath)) { + return this.renderStaleNodeSection(cg, node, includeCode); + } let code: string | null = null; let outline: string | null = null; if (includeCode) { @@ -4011,6 +4143,66 @@ export class ToolHandler { return this.formatNodeDetails(node, code, outline) + this.formatTrail(cg, node); } + // Whole-file fallback caps for a drifted file (#1474): small enough to fit + // codegraph_node's output cap (MAX_OUTPUT_LENGTH) with headroom for the + // header + trail. A file within these bounds is served WHOLE and CURRENT + // (Read-parity, correct by construction) instead of a possibly-wrong slice. + private static readonly STALE_WHOLE_FILE_MAX_LINES = 300; + private static readonly STALE_WHOLE_FILE_MAX_CHARS = 12000; + + /** + * codegraph_node render for a symbol whose file changed on disk after the + * last index sync (issue #1474). The indexed line range is no longer + * trustworthy, so no slice is emitted: a small file gets its full CURRENT + * source (Read-parity — sufficiency preserved, the agent still doesn't need + * Read); a large one gets an explicit notice steering to the tool's own + * file-read mode (or Read) — honest absence instead of confident wrongness. + * Location/signature stay (they're the index's answer) but are flagged as + * possibly shifted. + */ + private renderStaleNodeSection(cg: CodeGraph, node: Node, includeCode: boolean): string { + const lines: string[] = [ + `**${node.name}** (${node.kind})`, + '', + `**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`, + ]; + if (node.signature) { + lines.push(`**Signature:** \`${node.signature}\``); + } + lines.push(''); + let embedded = false; + if (includeCode) { + try { + const absPath = validatePathWithinRoot(cg.getProjectRoot(), node.filePath); + if (absPath && existsSync(absPath) && !isConfigLeafNode(node)) { + const content = readFileSync(absPath, 'utf-8'); + const body = content.replace(/\n+$/, ''); + if ( + body.length <= ToolHandler.STALE_WHOLE_FILE_MAX_CHARS && + body.split('\n').length <= ToolHandler.STALE_WHOLE_FILE_MAX_LINES + ) { + 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), + '```', + ); + embedded = true; + } + } + } catch { + /* fall through to the notice */ + } + } + if (!embedded) { + 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.`, + ); + } + return lines.join('\n') + this.formatTrail(cg, node); + } + /** * Build the "trail" for a symbol: its direct callees (what it calls) and * callers (what calls it), each with file:line — so codegraph_node doubles as