weavatrix 0.1.4 → 0.2.0

package/src/mcp/tools-impact-change.mjs

@@ -0,0 +1,261 @@
+// Symbol-aware change_impact implementation, isolated from the other hot impact tools so its
+// classifier/evidence contract can be tested without perturbing get_dependents or graph_diff.
+import {spawnSync} from 'node:child_process'
+import {childProcessEnv} from '../child-env.js'
+import {classifyChangeImpact} from '../analysis/change-classification.js'
+import {readCoverageForRepo} from '../analysis/coverage-reports.js'
+import {computeStaticTestReachability} from '../analysis/static-test-reachability.js'
+import {isStructuralRelation} from '../graph/relations.js'
+import {degreeOf, labelOf, rawGraph} from './graph-context.mjs'
+import {toolResult} from './tool-result.mjs'
+
+function gitLines(repoRoot, args) {
+    const result = spawnSync('git', ['-C', repoRoot, ...args], {encoding: 'utf8', timeout: 8000, env: childProcessEnv()})
+    if (result.status !== 0) return null
+    return String(result.stdout || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+}
+
+function gitValue(repoRoot, args) {
+    const result = spawnSync('git', ['-C', repoRoot, ...args], {encoding: 'utf8', timeout: 8000, env: childProcessEnv()})
+    if (result.status !== 0) return null
+    return String(result.stdout || '').trim() || null
+}
+
+function resolveImpactBase(repoRoot, requested) {
+    const candidates = requested ? [requested] : ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master']
+    for (const ref of candidates) {
+        const value = gitValue(repoRoot, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
+        if (value) return ref
+    }
+    return null
+}
+
+function reverseReach(g, seeds, maxDepth) {
+    const states = new Map([...seeds].map((id) => [String(id), {
+        runtimeDepth: 0, runtimeRelation: null, compileDepth: null, compileRelation: null,
+    }]))
+    const frontier = [...seeds].map((id) => ({id: String(id), depth: 0, compileOnly: false}))
+    for (let cursor = 0; cursor < frontier.length; cursor++) {
+        const current = frontier[cursor]
+        if (current.depth >= maxDepth) continue
+        for (const edge of g.inn.get(current.id) || []) {
+            if (isStructuralRelation(edge.relation) || edge.barrelProxy === true) continue
+            const id = String(edge.id)
+            const compileOnly = current.compileOnly || edge.typeOnly === true || edge.compileOnly === true
+            const depth = current.depth + 1
+            const entry = states.get(id) || {runtimeDepth: null, runtimeRelation: null, compileDepth: null, compileRelation: null}
+            const depthKey = compileOnly ? 'compileDepth' : 'runtimeDepth'
+            const relationKey = compileOnly ? 'compileRelation' : 'runtimeRelation'
+            if (entry[depthKey] != null && entry[depthKey] <= depth) continue
+            entry[depthKey] = depth
+            entry[relationKey] = edge.relation || 'rel'
+            states.set(id, entry)
+            frontier.push({id, depth, compileOnly})
+        }
+    }
+    return new Map([...states].map(([id, entry]) => [id, {
+        ...entry,
+        depth: entry.runtimeDepth ?? entry.compileDepth ?? 0,
+        compileOnly: entry.runtimeDepth == null,
+        relation: entry.runtimeDepth != null ? entry.runtimeRelation : entry.compileRelation,
+    }]))
+}
+
+const impactKind = (entry) => entry?.runtimeDepth != null
+    ? (entry.compileDepth != null ? `runtime + compile-time(d${entry.compileDepth})` : 'runtime')
+    : 'compile-time'
+
+const fileOfNode = (id) => {
+    const value = String(id)
+    const hash = value.indexOf('#')
+    return hash < 0 ? value : value.slice(0, hash)
+}
+
+const partialResult = (text, reason, status = 'UNAVAILABLE') => toolResult(text, {
+    status,
+    verdict: 'HIGH',
+    reasons: [reason],
+    changes: [],
+    seeds: {ids: [], unmappedIds: []},
+    blastRadius: {impacted: 0, runtime: 0, compileTimeOnly: 0, nodes: []},
+}, {completeness: {status: 'PARTIAL', reason}})
+
+export function tChangeImpactV2(g, args = {}, ctx = {}) {
+    if (!ctx.repoRoot) return partialResult(
+        'HIGH — change impact unavailable\nNo repository root is active; no diff can be classified safely.',
+        'Repository root unavailable.'
+    )
+
+    const explicit = Array.isArray(args.files)
+        ? [...new Set(args.files.map((file) => String(file).replace(/\\/g, '/').trim()).filter(Boolean))]
+        : null
+    if (explicit && !explicit.length) return partialResult(
+        'HIGH — invalid change set\nfiles was provided but empty; pass repo-relative paths, or omit it to diff local changes.',
+        'Explicit files list was empty.',
+        'INVALID'
+    )
+
+    const graph = rawGraph(ctx)
+    const providedDiff = typeof args.diff === 'string'
+    let sourceLabel
+    let classification
+    if (providedDiff) {
+        sourceLabel = explicit ? `from provided unified diff + ${explicit.length} file hint(s)` : 'from provided unified diff'
+        classification = classifyChangeImpact({repoRoot: ctx.repoRoot, graph, diffText: args.diff, files: explicit || []})
+    } else if (explicit) {
+        sourceLabel = `for ${explicit.length} provided file(s) (no diff; conservative fallback)`
+        classification = classifyChangeImpact({repoRoot: ctx.repoRoot, graph, files: explicit})
+    } else {
+        const base = resolveImpactBase(ctx.repoRoot, args.base ? String(args.base).trim() : '')
+        if (!base) return partialResult(
+            `HIGH — change impact unavailable\nCould not resolve base ref${args.base ? ` "${args.base}"` : ''}; pass base explicitly (for example origin/main or HEAD~1).`,
+            'Base ref could not be resolved.'
+        )
+        const mergeBase = gitValue(ctx.repoRoot, ['merge-base', base, 'HEAD']) || base
+        const untracked = gitLines(ctx.repoRoot, ['ls-files', '--others', '--exclude-standard']) || []
+        sourceLabel = `vs ${base}${mergeBase !== base ? ` (merge-base ${mergeBase.slice(0, 12)})` : ''}`
+        classification = classifyChangeImpact({repoRoot: ctx.repoRoot, graph, base: mergeBase, files: untracked})
+    }
+
+    if (!classification.files.length) return toolResult(`LOW — change impact ${sourceLabel}\nNo textual or untracked changes were found.`, {
+        status: 'COMPLETE',
+        verdict: 'LOW',
+        reasons: classification.reasons,
+        changes: [],
+        seeds: {ids: [], unmappedIds: []},
+        blastRadius: {impacted: 0, runtime: 0, compileTimeOnly: 0, nodes: []},
+    }, {completeness: {status: 'COMPLETE'}})
+
+    const changed = [...new Set(classification.files
+        .flatMap((file) => [file.oldPath, file.newPath])
+        .filter((file) => file && file !== '(diff unavailable)'))]
+    const changedSet = new Set(changed)
+    const seedIds = classification.seedIds.filter((id) => g.byId.has(String(id)))
+    const seeds = new Set(seedIds)
+    const unmappedSeedIds = classification.seedIds.filter((id) => !g.byId.has(String(id)))
+    const unmappedFiles = classification.files
+        .filter((file) => ![file.oldPath, file.newPath].some((path) => path && g.byId.has(String(path))))
+        .map((file) => file.path)
+
+    const maxDepth = Math.max(1, Math.min(4, Number(args.depth) || 2))
+    const cap = Math.max(5, Math.min(120, Number(args.max_nodes) || 40))
+    const reached = seeds.size ? reverseReach(g, seeds, maxDepth) : new Map()
+    const impacted = [...reached.entries()]
+        .filter(([id]) => !seeds.has(id) && !changedSet.has(fileOfNode(id)))
+        .map(([id, entry]) => ({id, depth: entry.depth, entry, degree: degreeOf(g, id), file: fileOfNode(id)}))
+        .sort((left, right) => left.depth - right.depth
+            || Number(left.entry.compileOnly) - Number(right.entry.compileOnly)
+            || right.degree - left.degree
+            || left.id.localeCompare(right.id))
+
+    // Measured coverage wins. Static reachability stays separately labelled and never becomes a
+    // synthetic coverage percentage.
+    const knownFiles = (graph.nodes || []).filter((node) => !String(node.id).includes('#') && node.source_file).map((node) => node.source_file)
+    const coverage = readCoverageForRepo(ctx.repoRoot, knownFiles)
+    const coverageOf = (file) => coverage.get(String(file).replace(/\\/g, '/'))?.pct ?? null
+    const hasCoverage = coverage.size > 0
+    const staticTests = computeStaticTestReachability(graph, {repoRoot: ctx.repoRoot})
+    const staticByFile = new Map(staticTests.reachable.map((entry) => [entry.file, entry.nearestTests[0]]))
+    const staticUnreachable = new Set(staticTests.unreachable)
+    const testEvidenceFor = (file) => {
+        const normalized = String(file).replace(/\\/g, '/')
+        const actualCoverage = coverageOf(normalized)
+        const nearest = staticByFile.get(normalized)
+        return {
+            actualCoverage,
+            staticTestReachability: nearest ? {
+                status: 'REACHABLE',
+                test: nearest.test,
+                distance: nearest.distance,
+                confidence: nearest.confidence,
+                path: nearest.path,
+            } : staticUnreachable.has(normalized) ? {status: 'NO_PATH'} : {status: 'NOT_INDEXED'},
+        }
+    }
+    const evidenceLabel = (file) => {
+        const evidence = testEvidenceFor(file)
+        if (evidence.actualCoverage != null) return `cov ${Math.round(evidence.actualCoverage * 100)}%`
+        const reachability = evidence.staticTestReachability
+        if (reachability.status === 'REACHABLE') return `static-test d${reachability.distance} ${reachability.confidence}`
+        return reachability.status === 'NO_PATH' ? 'no static test path' : 'test evidence n/a'
+    }
+
+    const shown = impacted.slice(0, cap)
+    const runtimeImpacted = impacted.filter((entry) => !entry.entry.compileOnly).length
+    const compileImpacted = impacted.length - runtimeImpacted
+    const coverageHotspots = hasCoverage
+        ? shown.filter((node) => { const value = coverageOf(node.file); return value != null && value < 0.5 && node.degree >= 5 })
+        : []
+    const nodes = shown.map((node) => ({
+        id: node.id,
+        label: labelOf(g, node.id),
+        file: node.file,
+        depth: node.depth,
+        kind: impactKind(node.entry),
+        relation: node.entry.relation || 'rel',
+        degree: node.degree,
+        testEvidence: testEvidenceFor(node.file),
+    }))
+    const changeLines = classification.files.slice(0, 30).flatMap((file) => [
+        `  [${file.classification}] ${file.path} — ${file.reason} (${file.seedIds.length} seed${file.seedIds.length === 1 ? '' : 's'})`,
+        ...file.symbols.slice(0, 8).map((symbol) => `      ↳ [${symbol.classification}] ${symbol.label} [${symbol.id}]`),
+    ])
+    const warnings = []
+    if (!classification.ok) warnings.push({code: 'CHANGE_CLASSIFICATION_PARTIAL', message: classification.reasons.join(' ')})
+    if (unmappedFiles.length) warnings.push({code: 'CHANGED_FILES_UNMAPPED', message: `${unmappedFiles.length} changed file(s) are absent from the current graph.`})
+    if (unmappedSeedIds.length) warnings.push({code: 'CHANGE_SEEDS_UNMAPPED', message: `${unmappedSeedIds.length} classified seed(s) are absent from the current graph.`})
+
+    const text = [
+        `${classification.verdict} — symbol-aware change impact ${sourceLabel}`,
+        ...classification.reasons.map((reason) => `Reason: ${reason}`),
+        `Changed evidence: ${classification.files.length} file(s), ${classification.summary.symbols} mapped symbol(s) → ${seeds.size} exact graph seed(s).`,
+        ...changeLines,
+        classification.files.length > 30 ? `  … +${classification.files.length - 30} more changed files` : null,
+        '',
+        impacted.length
+            ? `Blast radius: ${impacted.length} impacted node(s) within ${maxDepth} reverse hop(s) (${runtimeImpacted} runtime, ${compileImpacted} compile-time-only), showing ${shown.length}:`
+            : seeds.size ? `Blast radius: nothing else depends on the exact changed symbols within ${maxDepth} hop(s).` : `Blast radius: 0 — additive/metadata-only changes do not inherit the containing file's legacy importers.`,
+        hasCoverage
+            ? 'Test evidence: measured coverage is shown where mapped; static reachability remains separate in structured output.'
+            : `Test evidence: actualCoverage NOT_AVAILABLE; static paths only (${staticTests.reachableFiles}/${staticTests.productFiles} product files reachable from indexed tests).`,
+        ...shown.map((node) => `  [d${node.depth} ${impactKind(node.entry)}] ${node.entry.relation || 'rel'}  ${labelOf(g, node.id)}  (deg ${node.degree}, ${evidenceLabel(node.file)})  [${node.id}]`),
+        coverageHotspots.length ? '' : null,
+        coverageHotspots.length ? 'Measured-coverage hotspots in the blast radius (<50%, deg ≥5):' : null,
+        ...coverageHotspots.slice(0, 10).map((node) => `  ${labelOf(g, node.id)}  (cov ${Math.round(coverageOf(node.file) * 100)}%, deg ${node.degree})  ${node.file}`),
+        '',
+        'Drill into an impacted node with get_dependents/read_source; coverage_map distinguishes measured coverage from static reachability.',
+    ].filter((line) => line != null).join('\n')
+
+    const complete = classification.ok && !unmappedFiles.length && !unmappedSeedIds.length
+    return toolResult(text, {
+        status: complete ? 'COMPLETE' : 'PARTIAL',
+        verdict: classification.verdict,
+        reasons: classification.reasons,
+        source: {label: sourceLabel, kind: classification.source},
+        changes: classification.files,
+        classification: {summary: classification.summary, bounds: classification.bounds},
+        seeds: {ids: [...seeds].sort(), unmappedIds: unmappedSeedIds},
+        blastRadius: {
+            depth: maxDepth,
+            impacted: impacted.length,
+            runtime: runtimeImpacted,
+            compileTimeOnly: compileImpacted,
+            nodes,
+        },
+        testEvidence: {
+            actualCoverage: hasCoverage ? 'AVAILABLE' : 'NOT_AVAILABLE',
+            staticTestReachability: {
+                kind: staticTests.kind,
+                testFiles: staticTests.testFiles,
+                productFiles: staticTests.productFiles,
+                reachableFiles: staticTests.reachableFiles,
+                bounds: staticTests.bounds,
+            },
+        },
+        unmappedFiles,
+    }, {
+        warnings,
+        page: {shown: shown.length, total: impacted.length, capped: shown.length < impacted.length},
+        completeness: {status: complete ? 'COMPLETE' : 'PARTIAL'},
+    })
+}

package/src/mcp/tools-impact.mjs

@@ -10,6 +10,8 @@ import {
 } from './graph-context.mjs'
 import {readCoverageForRepo} from '../analysis/coverage-reports.js'
 import {isStructuralRelation} from '../graph/relations.js'
+import {tChangeImpactV2} from './tools-impact-change.mjs'
+import {buildGraphAtGitRef} from '../analysis/git-ref-graph.js'
 
 function reverseReach(g, seeds, maxDepth) {
     const states = new Map([...seeds].map((id) => [String(id), {
@@ -20,7 +22,7 @@ function reverseReach(g, seeds, maxDepth) {
         const current = frontier[cursor]
         if (current.depth >= maxDepth) continue
         for (const e of g.inn.get(current.id) || []) {
-            if (isStructuralRelation(e.relation)) continue
+            if (isStructuralRelation(e.relation) || e.barrelProxy === true) continue
             const id = String(e.id)
             const compileOnly = current.compileOnly || e.typeOnly === true || e.compileOnly === true
             const depth = current.depth + 1
@@ -89,11 +91,20 @@ export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
 }
 
 // Re-query the last rebuild's before/after pair (graph.prev.json vs graph.json), optionally scoped.
-export function tGraphDiff(g, args, ctx) {
-    const prevPath = prevGraphPathFor(ctx.graphPath)
+export async function tGraphDiff(g, args, ctx) {
     let prev
-    try { prev = JSON.parse(readFileSync(prevPath, 'utf8')) } catch {
-        return `No previous graph state at ${prevPath} — rebuild_graph saves one automatically (a single prior state is kept).`
+    let baselineLabel = 'previous rebuild state'
+    if (args.base_ref) {
+        if (!ctx.repoRoot) return 'A Git-ref graph diff needs the active repository root.'
+        const built = await buildGraphAtGitRef(ctx.repoRoot, args.base_ref)
+        if (!built.ok) return `Could not build the baseline graph: ${built.error}`
+        prev = built.graph
+        baselineLabel = `${built.ref} (${built.commit.slice(0, 12)})`
+    } else {
+        const prevPath = prevGraphPathFor(ctx.graphPath)
+        try { prev = JSON.parse(readFileSync(prevPath, 'utf8')) } catch {
+            return `No previous graph state at ${prevPath} — pass base_ref (for example HEAD~1 or main), or run rebuild_graph to save one automatically.`
+        }
     }
     const current = rawGraph(ctx)
     const filter = args.path ? String(args.path).replace(/\\/g, '/') : null
@@ -101,9 +112,11 @@ export function tGraphDiff(g, args, ctx) {
         nodes: (graph.nodes || []).filter((n) => String(n.id).startsWith(filter)),
         links: (graph.links || []).filter((l) => String(edgeEndpoint(l.source)).startsWith(filter) || String(edgeEndpoint(l.target)).startsWith(filter)),
         edgeTypesV: graph.edgeTypesV || 0,
+        barrelResolutionV: graph.barrelResolutionV || 0,
+        extractorSchemaV: graph.extractorSchemaV || 0,
     } : graph
     return [
-        `Graph diff (previous rebuild state → current)${filter ? `, scoped to ${filter}` : ''}:`,
+        `Graph diff (${baselineLabel} → current)${filter ? `, scoped to ${filter}` : ''}:`,
         formatGraphDiff(diffGraphs(scope(prev), scope(current)))
     ].join('\n')
 }
@@ -130,6 +143,12 @@ function resolveImpactBase(repoRoot, requested) {
 // can break, ranked by proximity + connectivity, with file-level test coverage attached so the
 // untested part of the blast radius stands out. The pre-PR review, in one call.
 export function tChangeImpact(g, args, ctx) {
+    return tChangeImpactV2(g, args, ctx)
+}
+
+// Kept private during the v2 rollout so the surrounding get_dependents/graph_diff implementation is
+// untouched; focused tests exercise the exported symbol-aware path above.
+function tChangeImpactLegacy(g, args, ctx) {
     if (!ctx.repoRoot) return 'change_impact needs the repo root (not provided to this server).'
     // Explicit file list (e.g. a PR's changed files) skips the local git diff entirely — this is how
     // a NOT-checked-out PR gets its impact assessed.

package/src/mcp-server.mjs

@@ -22,6 +22,10 @@ import process from 'node:process'
 import {loadGraph} from './mcp/graph-context.mjs'
 import {graphOutDirForRepo} from './graph/layout.js'
 import {createRequire} from 'node:module'
+import {createStalenessNoticeGate} from './mcp/staleness-notice.mjs'
+import {normalizeToolResult} from './mcp/tool-result.mjs'
+import {buildGraphForRepo} from './build-graph.js'
+import {persistedFreshnessMatches, repositoryFreshnessProbe} from './graph/freshness-probe.js'
 
 // version comes from package.json so serverInfo can never drift from the published package again
 const PKG_VERSION = (() => { try { return createRequire(import.meta.url)('../package.json').version } catch { return '0.0.0' } })()
@@ -33,7 +37,7 @@ const log = (...a) => process.stderr.write(`[weavatrix] ${a.join(' ')}\n`)
 // otherwise it is the graph.json path and the repo root follows it.
 let GRAPH_PATH = process.argv[2]
 let repoArg = process.argv[3]
-// caps ABSENT (undefined) = offline defaults (including explicit-call repo retargeting, no network).
+// caps ABSENT (undefined) = offline defaults (explicit local retargeting, no network).
 // PRESENT (even the empty string) = explicit set — see catalog.loadHotApi.
 let CAPS_ARG = process.argv[4]
 try {
@@ -87,6 +91,53 @@ async function main() {
     log(`capabilities: ${[...api.caps].join(',') || '(none)'} (${api.tools.length} tools)`)
 
     let protocolVersion = DEFAULT_PROTOCOL
+    const staleNotices = createStalenessNoticeGate()
+    // Only build/retarget tools mutate the process-wide graph target. Serialize those mutations while
+    // ordinary tools use a per-call graph/context snapshot, so an explicitly retargetable registration
+    // cannot mix one repo's in-memory graph with another repo's source root under concurrent MCP calls.
+    let targetMutation = Promise.resolve()
+    const refreshProbeCache = new Map()
+    const configuredDebounce = process.env.WEAVATRIX_AUTO_REFRESH_DEBOUNCE_MS == null
+        ? 2_000
+        : Number(process.env.WEAVATRIX_AUTO_REFRESH_DEBOUNCE_MS)
+    const refreshDebounceMs = Math.max(0, Math.min(5_000, Number.isFinite(configuredDebounce) ? configuredDebounce : 2_000))
+    const autoRefresh = async (callCtx, currentGraph) => {
+        if (!callCtx?.repoRoot || !callCtx?.graphPath) return {graph: null, refresh: null}
+        const probeKey = `${callCtx.graphPath}\0${currentGraph?.graphBuildMode || 'full'}`
+        const cachedProbe = refreshProbeCache.get(probeKey)
+        if (currentGraph && cachedProbe && Date.now() - cachedProbe.checkedAt < refreshDebounceMs) {
+            return {graph: currentGraph, refresh: {kind: 'none', revision: currentGraph.graphRevision || null, changedFiles: 0}}
+        }
+        const beforeProbe = repositoryFreshnessProbe(callCtx.repoRoot)
+        if (beforeProbe && currentGraph && (
+            cachedProbe?.probe === beforeProbe
+            || persistedFreshnessMatches(currentGraph, beforeProbe, currentGraph.graphBuildMode || 'full')
+        )) {
+            refreshProbeCache.set(probeKey, {probe: beforeProbe, checkedAt: Date.now()})
+            return {graph: currentGraph, refresh: {kind: 'none', revision: currentGraph.graphRevision || null, changedFiles: 0}}
+        }
+        const result = await buildGraphForRepo(callCtx.repoRoot, {
+            mode: currentGraph?.graphBuildMode || 'full',
+            scope: '',
+            outDir: dirname(callCtx.graphPath),
+        })
+        if (!result.ok) throw new Error(result.error || 'automatic graph refresh failed')
+        api.resetStalenessCache()
+        const fresh = loadGraph(callCtx.graphPath)
+        const afterProbe = repositoryFreshnessProbe(callCtx.repoRoot)
+        if (afterProbe && afterProbe === beforeProbe) refreshProbeCache.set(probeKey, {probe: afterProbe, checkedAt: Date.now()})
+        else refreshProbeCache.delete(probeKey)
+        const update = result.refresh || {kind: 'full', changedFiles: [], reason: 'automatic-refresh'}
+        return {
+            graph: fresh,
+            refresh: {
+                kind: update.kind,
+                revision: update.revision || fresh.graphRevision || null,
+                changedFiles: Array.isArray(update.changedFiles) ? update.changedFiles.length : 0,
+                notice: update.kind === 'none' ? undefined : `Graph ${update.kind === 'incremental' ? 'incrementally refreshed' : 'rebuilt'} before this answer (${update.reason || 'repository changed'}).`,
+            },
+        }
+    }
     const send = (msg) => process.stdout.write(JSON.stringify(msg) + '\n')
     const reply = (id, result) => send({jsonrpc: '2.0', id, result})
     const fail = (id, code, message) => send({jsonrpc: '2.0', id, error: {code, message}})
@@ -121,29 +172,61 @@ async function main() {
         if (method === 'ping') return reply(id, {})
         if (method === 'tools/list') {
             await maybeHotReload()
-            return reply(id, {tools: api.tools.map(({name, description, inputSchema}) => ({name, description, inputSchema}))})
+            return reply(id, {tools: api.tools.map(({name, description, inputSchema, outputSchema}) => ({name, description, inputSchema, outputSchema}))})
         }
         if (method === 'tools/call') {
             await maybeHotReload()
             const tool = api.byName.get(params?.name)
             if (!tool) return reply(id, {content: [{type: 'text', text: `Unknown tool: ${params?.name}`}], isError: true})
-            // action tools can establish/retarget a graph; read tools need one already loaded
-            if (!graph && tool.cap !== 'build' && tool.cap !== 'retarget') return reply(id, {content: [{type: 'text', text: `Graph unavailable: ${graphError}`}], isError: true})
-            try {
-                let text = String(await tool.run(graph, params?.arguments || {}, ctx))
-                if (graph && graph.edgeTypesV < 2 && (tool.cap === 'graph' || tool.cap === 'health')) {
-                    text += '\n\nWarning: this saved graph predates compile-only edge metadata (edge schema v2), so Rust module/use dependencies may be absent or misclassified. Call rebuild_graph once before acting on cycle, boundary, dependency, or blast-radius findings.'
-                }
-                // Graph answers silently reflect a point-in-time build — surface staleness on every graph tool.
-                if (tool.cap === 'graph') {
-                    const warn = api.stalenessLine(ctx)
-                    if (warn) text += `\n\n${warn}`
+            const refreshesGraph = tool.cap === 'graph' || tool.cap === 'health' || tool.refreshGraph === true
+            // Graph/health reads can establish a missing graph automatically when a repo root is known.
+            if (!graph && !refreshesGraph && tool.cap !== 'build' && tool.cap !== 'retarget') return reply(id, {content: [{type: 'text', text: `Graph unavailable: ${graphError}`}], isError: true})
+            const mutatesTarget = tool.cap === 'build' || tool.cap === 'retarget'
+            const graphSnapshot = graph
+            const callCtx = mutatesTarget ? ctx : {...ctx}
+            const execute = async () => {
+                try {
+                    // A queued rebuild must see a preceding retarget's graph, while non-mutating calls stay
+                    // pinned to the graph that was active when their request arrived.
+                    let refresh = null
+                    let callGraph = mutatesTarget ? graph : graphSnapshot
+                    if (!mutatesTarget && refreshesGraph) {
+                        const refreshed = await autoRefresh(callCtx, callGraph)
+                        if (refreshed.graph) {
+                            callGraph = refreshed.graph
+                            refresh = refreshed.refresh
+                            if (ctx.graphPath === callCtx.graphPath && ctx.repoRoot === callCtx.repoRoot) graph = callGraph
+                        }
+                    }
+                    const toolArgs = params?.arguments || {}
+                    const value = await tool.run(callGraph, toolArgs, callCtx)
+                    const warnings = []
+                    if (callGraph && callGraph.edgeTypesV < 2 && (tool.cap === 'graph' || tool.cap === 'health')) {
+                        warnings.push({code: 'EDGE_SCHEMA_OUTDATED', message: 'This saved graph predates compile-only edge metadata (edge schema v2); rebuild before acting on cycle, boundary, dependency, or blast-radius findings.'})
+                    }
+                    // Graph answers silently reflect a point-in-time build — surface staleness on every graph tool.
+                    const staleLine = tool.cap === 'graph' ? api.stalenessLine(callCtx) : null
+                    if (staleLine) warnings.push({code: 'GRAPH_STALE', message: staleLine})
+                    const normalized = normalizeToolResult({
+                        toolName: tool.name, value, args: toolArgs, ctx: callCtx, warnings, refresh,
+                        freshness: staleLine ? 'stale' : 'fresh',
+                    })
+                    let text = normalized.text
+                    if (toolArgs.output_format !== 'json') {
+                        const schemaWarning = warnings.find((warning) => warning.code === 'EDGE_SCHEMA_OUTDATED')
+                        if (schemaWarning) text += `\n\nWarning: ${schemaWarning.message}`
+                        if (staleLine && staleNotices.shouldShow({line: staleLine, graphPath: callCtx.graphPath, force: tool.name === 'graph_stats'})) text += `\n\n${staleLine}`
+                    }
+                    return reply(id, {content: [{type: 'text', text}], structuredContent: normalized.structured})
+                } catch (e) {
+                    log(`tool ${params?.name} threw: ${e.stack || e.message}`)
+                    return reply(id, {content: [{type: 'text', text: `Tool error: ${e.message}`}], isError: true})
                 }
-                return reply(id, {content: [{type: 'text', text}]})
-            } catch (e) {
-                log(`tool ${params?.name} threw: ${e.stack || e.message}`)
-                return reply(id, {content: [{type: 'text', text: `Tool error: ${e.message}`}], isError: true})
             }
+            if (!mutatesTarget && !refreshesGraph) return execute()
+            const pending = targetMutation.then(execute, execute)
+            targetMutation = pending.catch(() => {})
+            return pending
         }
         if (!isNotification) return fail(id, -32601, `Method not found: ${method}`)
     }

package/src/mcp-source-tools.mjs

@@ -3,6 +3,7 @@ import { spawnSync } from 'node:child_process'
 import { extname, join, relative } from 'node:path'
 import { resolveRepoPath } from './repo-path.js'
 import { childProcessEnv } from './child-env.js'
+import { toolResult } from './mcp/tool-result.mjs'
 
 const SEARCH_SKIP = new Set(['.git', 'node_modules', 'dist', 'build', 'out', '.next', 'coverage', 'vendor', '.venv', 'venv', 'env', 'target', '__pycache__', '.idea', '.vscode', '.cache', 'bin', 'obj', 'weavatrix-graphs'])
 const BINARY_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.pdf', '.zip', '.gz', '.tar', '.exe', '.dll', '.so', '.dylib', '.woff', '.woff2', '.ttf', '.eot', '.mp4', '.mp3', '.wasm', '.class', '.jar', '.node', '.bin'])
@@ -13,7 +14,7 @@ const MAX_SOURCE_CONTEXT_LINES = 1000
 function rgSearch(repoRoot, resolveRg, query, { isRegex, glob, maxResults }) {
     const rg = resolveRg()
     if (!rg) return null
-    const args = ['--line-number', '--no-heading', '--color', 'never', '--max-columns', '400', '-m', '30', '-i']
+    const args = ['--line-number', '--no-heading', '--color', 'never', '--hidden', '-g', '!.git/**', '-m', '100', '-i']
     if (!isRegex) args.push('--fixed-strings')
     if (glob) args.push('-g', glob)
     args.push('--', query, repoRoot)
@@ -95,11 +96,18 @@ export function searchCode({ repoRoot, resolveRg }, { query, is_regex = false, m
     const engine = matches ? 'ripgrep' : 'node'
     if (!matches) matches = nodeGrep(repoRoot, query, opts)
     const what = is_regex ? `/${query}/i` : `"${query}"`
-    if (!matches.length) return `No matches for ${what}${glob ? ` in ${glob}` : ''}.`
-    return [
+    if (!matches.length) return toolResult(
+        `No matches for ${what}${glob ? ` in ${glob}` : ''}.`,
+        {query, isRegex: !!is_regex, glob: glob || null, engine, matches: []},
+        {completeness: {status: 'complete', reason: 'search completed with no matches'}},
+    )
+    const text = [
         `${matches.length} match${matches.length === 1 ? '' : 'es'} for ${what}${glob ? ` (glob ${glob})` : ''} [${engine}]:`,
         ...matches.map((m) => `  ${m.file}:${m.line}:  ${m.text}`),
     ].join('\n')
+    return toolResult(text, {query, isRegex: !!is_regex, glob: glob || null, engine, matches}, {
+        completeness: {status: matches.length >= max ? 'bounded' : 'complete', limit: max},
+    })
 }
 
 export function readSource({ repoRoot, resolveNode, isSymbol }, g, { label, path, start_line, before = 3, after = 40 } = {}) {