weavatrix 0.1.1 → 0.1.3

package/src/mcp/tools-health.mjs

@@ -38,19 +38,38 @@ export function tFindDuplicates(g, args, ctx) {
     if (args.mode === 'semantic') {
         const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {nameTwins: true})
         const frags = data.frags
-        const groups = (data.nameTwins || [])
-            .map((t) => ({...t, members: t.members.filter((i) => (!skipTests || !frags[i].test) && frags[i].n >= tokMin)}))
-            .map((t) => ({...t, fileCount: new Set(t.members.map((i) => frags[i].file)).size}))
-            .filter((t) => t.members.length >= 2 && t.fileCount >= 2)
-        if (!groups.length) return 'No same-name symbol groups across files (semantic mode).'
-        const top = groups.slice(0, Math.min(30, Math.max(1, Number(args.top_n) || 15)))
-        const lines = top.map((t, k) => {
-            const verdict = t.simMax < 60 ? '  ⚠ DIVERGENT — same name, different bodies (drift hazard)' : t.simMin >= 90 ? '  near-identical — extract a shared module' : ''
-            const head = `${k + 1}. "${t.label}" — ${t.members.length} definitions in ${t.fileCount} files, similarity ${t.simMin}–${t.simMax}%${verdict}`
-            const sites = t.members.slice(0, 8).map((i) => `     ${frags[i].file}:${frags[i].start}-${frags[i].end}  (${frags[i].n} tok)`)
-            return [head, ...sites].join('\n')
+        const candidates = []
+        for (const twin of data.nameTwins || []) {
+            const allowed = new Set(twin.members.filter((i) => (!skipTests || !frags[i].test) && frags[i].n >= tokMin))
+            const pairs = (twin.pairs || []).filter((p) => allowed.has(p.a) && allowed.has(p.b))
+            if (!pairs.length) continue
+            const closest = pairs.slice().sort((a, b) => b.similarity - a.similarity)[0]
+            const farthest = pairs.slice().sort((a, b) => a.similarity - b.similarity)[0]
+            if (closest.similarity >= 85) candidates.push({kind: 'clone', label: twin.label, pair: closest})
+            if (farthest.similarity <= 45) candidates.push({kind: 'collision', label: twin.label, pair: farthest})
+        }
+        for (const item of candidates) item.tokens = frags[item.pair.a].n + frags[item.pair.b].n
+        candidates.sort((a, b) => {
+            if (a.kind !== b.kind) return a.kind === 'clone' ? -1 : 1
+            return a.kind === 'clone'
+                ? b.pair.similarity - a.pair.similarity || b.tokens - a.tokens
+                : b.tokens - a.tokens || a.pair.similarity - b.pair.similarity
         })
-        return `Found ${groups.length} same-name symbol group(s) across files (semantic mode; similarity = renamed-token jaccard, LOW = divergent copies). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nLow-similarity groups are the risky ones — same name, drifted behavior. read_source both sites to compare.`
+        if (!candidates.length) return 'No actionable same-name pairs across files (semantic mode; ambiguous middle-similarity pairs are suppressed).'
+        const top = candidates.slice(0, Math.min(30, Math.max(1, Number(args.top_n) || 15)))
+        const lines = top.map((item, k) => {
+            const a = frags[item.pair.a]
+            const b = frags[item.pair.b]
+            const verdict = item.kind === 'clone'
+                ? 'near-identical duplicate candidate — review, then extract shared logic if the contract is truly shared'
+                : 'name collision, not a duplicate — inspect only if these definitions should share a contract'
+            return [
+                `${k + 1}. "${item.label}" — ${item.pair.similarity}% similar; ${verdict}`,
+                `     ${a.file}:${a.start}-${a.end}  (${a.n} tok)`,
+                `     ${b.file}:${b.start}-${b.end}  (${b.n} tok)`,
+            ].join('\n')
+        })
+        return `Found ${candidates.length} actionable same-name pair(s) across files (semantic mode; one closest clone and/or farthest collision per name). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nThese are review candidates, not automatic refactors. Use read_source on both sites before changing code.`
     }
     const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {includeStrings})
     const groups = groupClones(data, {simMin, tokMin, mode, skipTests})
@@ -87,14 +106,15 @@ export async function tRunAudit(g, args, ctx) {
     const sev = audit.summary.bySeverity
     const bycat = audit.summary.byCategory
     const line = (f) => {
-        const where = f.file ? `  (${f.file}${f.symbol ? ` ${f.symbol}` : ''})` : f.package ? `  (pkg ${f.package}${f.version ? `@${f.version}` : ''})` : ''
+        const where = f.file ? `  (${f.file}${f.symbol ? ` ${f.symbol}` : ''})` : f.package ? `  (pkg ${f.package}${f.version ? `@${f.version}` : ''}${f.manifest ? `; ${f.manifest}` : ''})` : ''
         return `  [${f.severity}/${f.confidence || '?'}] ${f.rule}: ${f.title}${where}${f.fixHint ? `\n      fix: ${f.fixHint}` : ''}`
     }
+    const check = (name, state) => `${name} ${state?.status || 'ERROR'}${state?.detail ? ` — ${state.detail}` : ''}`
     return [
         `Internal audit of ${audit.repo} (${audit.scanned.files} files, ${audit.scanned.symbols} symbols, ${audit.scanned.externalImports} external imports; malware scan: ${audit.scanned.malwareScanMode}).`,
         `Severity: critical ${sev.critical}, high ${sev.high}, medium ${sev.medium}, low ${sev.low}, info ${sev.info}. Categories: unused ${bycat.unused}, structure ${bycat.structure}, vulnerability ${bycat.vulnerability}, malware ${bycat.malware}.`,
-        `Structure: ${audit.structureReport?.cycles ?? 0} cycle(s), ${audit.structureReport?.orphans ?? 0} orphan(s). Dead: ${audit.deadReport.deadFiles} file(s), ${audit.deadReport.unusedExports} unused export(s).`,
-        audit.scanned.advisoryDbDate ? `Advisory DB: ${audit.scanned.advisoryDbDate}.` : 'Advisory DB: never refreshed for this repo — known-vuln matching skipped (see refresh_advisories).',
+        `Structure: ${audit.structureReport?.runtimeCycles ?? audit.structureReport?.cycles ?? 0} runtime cycle(s), ${audit.structureReport?.typeCouplings ?? 0} type-induced coupling group(s), ${audit.structureReport?.orphans ?? 0} orphan(s); import edges: ${audit.structureReport?.runtimeImportEdges ?? audit.structureReport?.importEdges ?? 0} runtime + ${audit.structureReport?.typeOnlyImportEdges ?? 0} type-only. Dead: ${audit.deadReport.deadFiles} file(s), ${audit.deadReport.unusedExports} unused export(s).`,
+        `Checks: ${check('OSV', audit.checks?.osv)}; ${check('malware', audit.checks?.malware)}. A NOT_CHECKED/PARTIAL/ERROR check is incomplete or unknown, never a clean zero.`,
         ``,
         `Showing ${shown.length} of ${filtered.length} finding(s)${cat ? ` in category "${cat}"` : ''}${args.min_severity ? ` at ≥${args.min_severity}` : ''}:`,
         ...shown.map(line),
@@ -120,13 +140,17 @@ export function tModuleMap(g, args, ctx) {
     const topN = Math.max(1, Math.min(60, Number(args.top_n) || 25))
     const mods = agg.modules.slice(0, topN)
     const edges = agg.moduleEdges.slice(0, Math.min(50, topN * 2))
+    const typeEdges = (agg.typeOnlyModuleEdges || []).slice(0, Math.min(50, topN * 2))
     return [
-        `Module map: ${agg.totals.files} files in ${agg.modules.length} folder-modules, ${agg.totals.moduleEdges} module edges. Top ${mods.length}:`,
+        `Module map: ${agg.totals.files} files in ${agg.modules.length} folder-modules, ${agg.totals.moduleEdges} runtime module dependencies and ${agg.totals.typeOnlyModuleEdges || 0} type-only dependencies. Top ${mods.length}:`,
         ...mods.map((m) => `  ${m.name} — ${m.fileCount} files, ${m.symbolCount} symbols`),
         ``,
-        `Strongest module dependencies:`,
+        `Strongest runtime module dependencies:`,
         ...edges.map((e) => `  ${e.from} → ${e.to}  (${e.count})`),
-    ].join('\n')
+        typeEdges.length ? `` : null,
+        typeEdges.length ? `Type-only module dependencies (compile-time contracts, not runtime coupling):` : null,
+        ...typeEdges.map((e) => `  ${e.from} → ${e.to}  (${e.count})`),
+    ].filter((line) => line != null).join('\n')
 }
 
 // Coverage × graph: map an EXISTING coverage report (istanbul/lcov/coverage.py/Go — read offline,

package/src/mcp/tools-impact.mjs

@@ -3,12 +3,53 @@
 // Hot-reloadable (re-imported by catalog.mjs on change).
 import {readFileSync} from 'node:fs'
 import {spawnSync} from 'node:child_process'
+import {childProcessEnv} from '../child-env.js'
 import {
     isSymbol, degreeOf, labelOf, resolveNodeInfo, ambiguityNote,
     rawGraph, prevGraphPathFor, edgeEndpoint, diffGraphs, formatGraphDiff,
 } from './graph-context.mjs'
 import {readCoverageForRepo} from '../analysis/coverage-reports.js'
 
+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 e of g.inn.get(current.id) || []) {
+            if (e.relation === 'contains') continue
+            const id = String(e.id)
+            const compileOnly = current.compileOnly || e.typeOnly === 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] = e.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) => {
+    if (entry?.runtimeDepth != null) {
+        return entry.compileDepth != null ? `runtime + compile-time(d${entry.compileDepth})` : 'runtime'
+    }
+    return 'compile-time'
+}
+
 // Transitive blast-radius: who is affected if this node changes. Walks REVERSE dependency edges
 // (calls/imports/inherits — not structural `contains`) out to `depth`. For a symbol, also seeds its
 // containing file, because importers depend on the file rather than the individual symbol.
@@ -29,26 +70,10 @@ export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
             seeds.add(containingFile)
         }
     }
-    const depthOf = new Map([...seeds].map((s) => [s, 0]))
-    const relOf = new Map()
-    let frontier = [...seeds]
-    for (let d = 0; d < maxDepth && frontier.length; d++) {
-        const next = []
-        for (const cur of frontier) {
-            for (const e of g.inn.get(cur) || []) {
-                if (e.relation === 'contains') continue // structural nesting is not a dependency
-                const nid = String(e.id)
-                if (depthOf.has(nid)) continue
-                depthOf.set(nid, d + 1)
-                relOf.set(nid, e.relation || 'rel')
-                next.push(nid)
-            }
-        }
-        frontier = next
-    }
-    const ranked = [...depthOf.entries()]
+    const reached = reverseReach(g, seeds, maxDepth)
+    const ranked = [...reached.entries()]
         .filter(([nid]) => !seeds.has(nid))
-        .map(([nid, d]) => ({id: nid, d, deg: degreeOf(g, nid)}))
+        .map(([nid, entry]) => ({id: nid, d: entry.depth, entry, deg: degreeOf(g, nid)}))
         .sort((a, b) => a.d - b.d || b.deg - a.deg)
     if (!ranked.length) return [note, `No dependents found for ${n.label ?? id} within depth ${maxDepth} — nothing in the graph calls, imports, or inherits it.`].filter(Boolean).join('\n')
     const shown = ranked.slice(0, cap)
@@ -56,7 +81,7 @@ export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
         note,
         `Dependents of ${n.label ?? id} (reverse calls/imports/inherits, depth ≤${maxDepth}): ${ranked.length} found, showing ${shown.length} by proximity + connectivity.`,
         containingFile ? `Includes importers of its containing file ${labelOf(g, containingFile)}.` : null,
-        ...shown.map((r) => `  [d${r.d}] ${relOf.get(r.id) || 'rel'}  ${labelOf(g, r.id)}  (deg ${r.deg})  [${r.id}]`),
+        ...shown.map((r) => `  [d${r.d} ${impactKind(r.entry)}] ${r.entry.relation || 'rel'}  ${labelOf(g, r.id)}  (deg ${r.deg})  [${r.id}]`),
     ].filter(Boolean).join('\n')
 }
 
@@ -71,7 +96,8 @@ export function tGraphDiff(g, args, ctx) {
     const filter = args.path ? String(args.path).replace(/\\/g, '/') : null
     const scope = (graph) => filter ? {
         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))
+        links: (graph.links || []).filter((l) => String(edgeEndpoint(l.source)).startsWith(filter) || String(edgeEndpoint(l.target)).startsWith(filter)),
+        edgeTypesV: graph.edgeTypesV || 0,
     } : graph
     return [
         `Graph diff (previous rebuild state → current)${filter ? `, scoped to ${filter}` : ''}:`,
@@ -81,7 +107,7 @@ export function tGraphDiff(g, args, ctx) {
 
 // ---- change impact -------------------------------------------------------------------------------
 function gitLines(repoRoot, args) {
-    const res = spawnSync('git', ['-C', repoRoot, ...args], {encoding: 'utf8', timeout: 8000})
+    const res = spawnSync('git', ['-C', repoRoot, ...args], {encoding: 'utf8', timeout: 8000, env: childProcessEnv()})
     if (res.status !== 0) return null
     return String(res.stdout || '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean)
 }
@@ -89,7 +115,7 @@ function gitLines(repoRoot, args) {
 function resolveImpactBase(repoRoot, requested) {
     const candidates = requested ? [requested] : ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master']
     for (const ref of candidates) {
-        const ok = spawnSync('git', ['-C', repoRoot, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {encoding: 'utf8', timeout: 8000})
+        const ok = spawnSync('git', ['-C', repoRoot, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {encoding: 'utf8', timeout: 8000, env: childProcessEnv()})
         if (ok.status === 0) return ref
     }
     return null
@@ -143,27 +169,11 @@ export function tChangeImpact(g, args, ctx) {
 
     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 depthOf = new Map([...seeds].map((s) => [s, 0]))
-    const relOf = new Map()
-    let frontier = [...seeds]
-    for (let d = 0; d < maxDepth && frontier.length; d++) {
-        const next = []
-        for (const cur of frontier) {
-            for (const e of g.inn.get(cur) || []) {
-                if (e.relation === 'contains') continue
-                const nid = String(e.id)
-                if (depthOf.has(nid)) continue
-                depthOf.set(nid, d + 1)
-                relOf.set(nid, e.relation || 'rel')
-                next.push(nid)
-            }
-        }
-        frontier = next
-    }
+    const reached = reverseReach(g, seeds, maxDepth)
     const fileOfNode = (id) => { const s = String(id); const h = s.indexOf('#'); return h < 0 ? s : s.slice(0, h) }
-    const impacted = [...depthOf.entries()]
+    const impacted = [...reached.entries()]
         .filter(([nid]) => !seeds.has(nid) && !changedSet.has(fileOfNode(nid)))
-        .map(([nid, d]) => ({id: nid, d, deg: degreeOf(g, nid), file: fileOfNode(nid)}))
+        .map(([nid, entry]) => ({id: nid, d: entry.depth, entry, deg: degreeOf(g, nid), file: fileOfNode(nid)}))
         .sort((a, b) => a.d - b.d || b.deg - a.deg)
 
     // coverage overlay from EXISTING reports (fractions 0..1) — see coverage_map for details
@@ -171,6 +181,7 @@ export function tChangeImpact(g, args, ctx) {
     const coverage = readCoverageForRepo(ctx.repoRoot, knownFiles)
     const covOf = (file) => coverage.get(String(file).replace(/\\/g, '/'))?.pct ?? null
     const pctStr = (v) => (v == null ? 'cov n/a' : `cov ${Math.round(v * 100)}%`)
+    const hasCoverage = coverage.size > 0
 
     const shown = impacted.slice(0, cap)
     const untestedHotspots = shown.filter((n) => { const c = covOf(n.file); return c != null && c < 0.5 && n.deg >= 5 })
@@ -179,7 +190,8 @@ export function tChangeImpact(g, args, ctx) {
         impacted.length
             ? `${impacted.length} impacted node(s) within ${maxDepth} reverse hop(s), showing ${shown.length}:`
             : `Nothing else in the graph depends on the changed code within ${maxDepth} hop(s).`,
-        ...shown.map((n) => `  [d${n.d}] ${relOf.get(n.id) || 'rel'}  ${labelOf(g, n.id)}  (deg ${n.deg}, ${pctStr(covOf(n.file))})  [${n.id}]`),
+        hasCoverage ? `Coverage: existing report mapped where available.` : `Coverage: unavailable (no supported report found); per-node coverage labels omitted.`,
+        ...shown.map((n) => `  [d${n.d} ${impactKind(n.entry)}] ${n.entry.relation || 'rel'}  ${labelOf(g, n.id)}  (deg ${n.deg}${hasCoverage ? `, ${pctStr(covOf(n.file))}` : ''})  [${n.id}]`),
         untestedHotspots.length ? `` : null,
         untestedHotspots.length ? `Untested hotspots in the blast radius (<50% coverage, deg ≥5) — cover these before shipping:` : null,
         ...untestedHotspots.slice(0, 10).map((n) => `  ${labelOf(g, n.id)}  (${pctStr(covOf(n.file))}, deg ${n.deg})  ${n.file}`),

package/src/mcp-rg.mjs

@@ -1,6 +1,7 @@
 import { readdirSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { childProcessEnv } from './child-env.js'
 import { createRequire } from 'node:module'
 import process from 'node:process'
 
@@ -42,7 +43,7 @@ export function createRgResolver(selfDir) {
         } catch { /* optional packaged ripgrep path */ }
         for (const c of editorRgCandidates()) if (existsSync(c)) return (rgPath = c)
         try {
-            const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['rg'], {encoding: 'utf8'})
+            const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['rg'], {encoding: 'utf8', env: childProcessEnv()})
             const p = probe.status === 0 ? probe.stdout.split(/\r?\n/)[0].trim() : ''
             if (p && existsSync(p)) return (rgPath = p)
         } catch { /* optional PATH probe */ }

package/src/mcp-server.mjs

@@ -15,12 +15,11 @@
 // go to stderr. Two argv forms:
 //   weavatrix-mcp <repoRoot> [caps]               — graph path derived from the standard layout
 //   weavatrix-mcp <graph.json> <repoRoot> [caps]  — explicit graph file (classic form)
-import {existsSync, statSync} from 'node:fs'
+import {existsSync, statSync, realpathSync} from 'node:fs'
 import {join, dirname} from 'node:path'
 import {fileURLToPath} from 'node:url'
 import process from 'node:process'
 import {loadGraph} from './mcp/graph-context.mjs'
-import {loadHotApi, HOT_FILES} from './mcp/catalog.mjs'
 import {graphOutDirForRepo} from './graph/layout.js'
 import {createRequire} from 'node:module'
 
@@ -34,19 +33,20 @@ 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) = no per-repo config → ALL tools. PRESENT (even the empty string, which a
-// registration may pass for a zero-capability selection) = explicit set — see catalog.loadHotApi.
+// caps ABSENT (undefined) = offline defaults (including explicit-call repo retargeting, no network).
+// PRESENT (even the empty string) = explicit set — see catalog.loadHotApi.
 let CAPS_ARG = process.argv[4]
 try {
     if (GRAPH_PATH && statSync(GRAPH_PATH).isDirectory()) {
-        repoArg = GRAPH_PATH.replace(/[\\/]+$/, '')
+        repoArg = realpathSync.native(GRAPH_PATH)
         CAPS_ARG = process.argv[3]
         GRAPH_PATH = join(graphOutDirForRepo(repoArg), 'graph.json')
-        if (!existsSync(GRAPH_PATH)) log(`no graph built yet for ${repoArg} — ask the agent to call rebuild_graph (or open_repo) once; it builds into the standard weavatrix-graphs layout`)
+        if (!existsSync(GRAPH_PATH)) log(`no graph built yet for ${repoArg} — ask the agent to call rebuild_graph; it builds into the standard weavatrix-graphs layout`)
     }
 } catch { /* argv[2] is not a directory → classic <graph.json> <repoRoot> form */ }
 // repo source root for search_code / read_source; null → those tools degrade.
-const REPO_ROOT = repoArg && existsSync(repoArg) ? repoArg : null
+let REPO_ROOT = null
+try { if (repoArg && statSync(repoArg).isDirectory()) REPO_ROOT = realpathSync.native(repoArg) } catch { /* invalid repo root */ }
 
 // ---- hot reload of tool implementations -----------------------------------------------------------
 // Node caches modules at spawn, so edits to the tool code would otherwise be invisible until the MCP
@@ -55,16 +55,19 @@ const REPO_ROOT = repoArg && existsSync(repoArg) ? repoArg : null
 // swap the tool table, then notify the client. The stdio shell, graph-context (its caches), and the
 // analysis engines are NOT swapped — changing those still needs a reconnect.
 const MCP_DIR = join(dirname(fileURLToPath(import.meta.url)), 'mcp')
-function hotVersion() {
+const CATALOG_URL = new URL('./mcp/catalog.mjs', import.meta.url)
+const loadCatalog = (version = 0) => import(version ? `${CATALOG_URL.href}?v=${version}` : CATALOG_URL.href)
+function hotVersion(hotFiles) {
     let v = 0
-    for (const f of HOT_FILES) {
+    for (const f of hotFiles) {
         try { const t = statSync(join(MCP_DIR, f)).mtimeMs; if (t > v) v = t } catch { /* missing file just doesn't bump the version */ }
     }
     return v
 }
 
 async function main() {
-    let api = await loadHotApi(0, CAPS_ARG)
+    let catalog = await loadCatalog()
+    let api = await catalog.loadHotApi(0, CAPS_ARG)
     let graph = null
     let graphError = null
     // ctx owns the CURRENT target: rebuild_graph reloads it, open_repo retargets graphPath/repoRoot
@@ -81,20 +84,23 @@ async function main() {
         log(`failed to load graph: ${e.message}`)
     }
     log(`repo root: ${REPO_ROOT || '(none — source/action tools disabled)'}`)
-    log(`capabilities: ${api.caps ? [...api.caps].join(',') : 'all'} (${api.tools.length} tools)`)
+    log(`capabilities: ${[...api.caps].join(',') || '(none)'} (${api.tools.length} tools)`)
 
     let protocolVersion = DEFAULT_PROTOCOL
     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}})
 
-    let loadedVersion = hotVersion()
+    let loadedVersion = hotVersion(catalog.HOT_FILES)
     let lastFailedVersion = 0
     const maybeHotReload = async () => {
-        const v = hotVersion()
+        const v = hotVersion(catalog.HOT_FILES)
         if (v <= loadedVersion || v === lastFailedVersion) return
         try {
-            api = await loadHotApi(v, CAPS_ARG)
+            const nextCatalog = await loadCatalog(v)
+            const nextApi = await nextCatalog.loadHotApi(v, CAPS_ARG)
+            catalog = nextCatalog
+            api = nextApi
             loadedVersion = v
             log(`hot-reloaded tool implementations from changed source (${api.tools.length} tools)`)
             send({jsonrpc: '2.0', method: 'notifications/tools/list_changed'})
@@ -121,10 +127,13 @@ async function main() {
             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 (rebuild_graph) don't need a currently-loaded graph; read tools do
-            if (!graph && tool.cap !== 'build') return reply(id, {content: [{type: 'text', text: `Graph unavailable: ${graphError}`}], 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 < 1 && (tool.cap === 'graph' || tool.cap === 'health')) {
+                    text += '\n\nWarning: this saved graph predates typed import edges, so type-only imports cannot be separated from runtime dependencies. 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)

package/src/mcp-source-tools.mjs

@@ -1,10 +1,14 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 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'
 
 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'])
 const MAX_SEARCH_FILE_BYTES = 1024 * 1024
+const MAX_SOURCE_FILE_BYTES = 2 * 1024 * 1024
+const MAX_SOURCE_CONTEXT_LINES = 1000
 
 function rgSearch(repoRoot, resolveRg, query, { isRegex, glob, maxResults }) {
     const rg = resolveRg()
@@ -13,7 +17,7 @@ function rgSearch(repoRoot, resolveRg, query, { isRegex, glob, maxResults }) {
     if (!isRegex) args.push('--fixed-strings')
     if (glob) args.push('-g', glob)
     args.push('--', query, repoRoot)
-    const res = spawnSync(rg, args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, timeout: 15000 })
+    const res = spawnSync(rg, args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, timeout: 15000, env: childProcessEnv() })
     if (res.status !== 0 && res.status !== 1) return null
     const out = []
     for (const line of (res.stdout || '').split(/\r?\n/)) {
@@ -122,14 +126,21 @@ export function readSource({ repoRoot, resolveNode, isSymbol }, g, { label, path
     }
     // explicit anchor wins: window = start_line-before .. start_line+after (how a path read escapes the file head)
     if (start_line != null && Number(start_line) > 0) focusLine = Math.floor(Number(start_line))
-    const abs = join(repoRoot, file)
-    if (!existsSync(abs)) return `File not found: ${file}`
+    const resolved = resolveRepoPath(repoRoot, file)
+    if (resolved.reason === 'escape') return `Refusing to read "${file}": path escapes the repository root.`
+    if (resolved.reason === 'not-found') return `File not found: ${file}`
+    if (!resolved.ok) return `Could not resolve ${file} inside the repository root.`
+    const abs = resolved.path
+    let st
+    try { st = statSync(abs) } catch (e) { return `Could not inspect ${file}: ${e.message}` }
+    if (!st.isFile()) return `Could not read ${file}: not a regular file.`
+    if (st.size > MAX_SOURCE_FILE_BYTES) return `Could not read ${file}: file exceeds the ${MAX_SOURCE_FILE_BYTES / 1024 / 1024} MB source-read limit.`
     let text
     try { text = readFileSync(abs, 'utf8') } catch (e) { return `Could not read ${file}: ${e.message}` }
     const lines = text.split(/\r?\n/)
     if (focusLine) focusLine = Math.min(focusLine, lines.length) // an anchor past EOF shows the tail, not nothing
-    const b = Math.max(0, Number(before) || 0)
-    const a = Math.max(1, Number(after) || 40)
+    const b = Math.min(MAX_SOURCE_CONTEXT_LINES, Math.max(0, Number(before) || 0))
+    const a = Math.min(MAX_SOURCE_CONTEXT_LINES, Math.max(1, Number(after) || 40))
     const start = focusLine ? Math.max(1, focusLine - b) : 1
     const end = focusLine ? Math.min(lines.length, focusLine + a) : Math.min(lines.length, 1 + b + a)
     const width = String(end).length

package/src/process.js

@@ -1,5 +1,6 @@
 // Subprocess runner shared by the search engines and security sweeps.
 import { spawn } from "node:child_process";
+import { childProcessEnv } from "./child-env.js";
 
 // Windows: .cmd/.ps1 shims (npx, etc.) can't be spawned directly by Node — they need a
 // shell. With shell:true Node does NOT quote args, so we build a quoted command line ourselves
@@ -18,13 +19,13 @@ export function runCommand(command, args = [], options = {}) {
     const child = needsShell
       ? spawn([command, ...args].map(winQuote).join(" "), [], {
           cwd: options.cwd || undefined,
-          env: { ...process.env, ...(options.env || {}) },
+          env: childProcessEnv(options.env || {}),
           shell: true,
           windowsHide: true
         })
       : spawn(command, args, {
           cwd: options.cwd || undefined,
-          env: { ...process.env, ...(options.env || {}) },
+          env: childProcessEnv(options.env || {}),
           windowsHide: true
         });
 
@@ -46,7 +47,7 @@ export function runCommand(command, args = [], options = {}) {
     const killTree = () => {
       if (process.platform === "win32" && child.pid) {
         try {
-          spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true });
+          spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true, env: childProcessEnv() });
         } catch {
           try { child.kill(); } catch { /* process may already be gone */ }
         }

package/src/repo-path.js

@@ -0,0 +1,53 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export function isPathInside(root, target) {
+  const rel = relative(root, target);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+// Cache the canonical root for callers that resolve many graph-derived paths.
+export function createRepoBoundary(repoRoot) {
+  let root;
+  let rootError;
+  try {
+    root = realpathSync.native(repoRoot);
+  } catch (error) {
+    rootError = error;
+  }
+
+  return {
+    root,
+    resolve(candidate) {
+      if (!root) return { ok: false, reason: "invalid-root", error: rootError };
+      const input = String(candidate ?? "");
+      if (!input || input.includes("\0")) return { ok: false, reason: "invalid-path" };
+      if (isAbsolute(input)) return { ok: false, reason: "escape" };
+
+      let lexical;
+      try {
+        lexical = resolve(root, input);
+      } catch (error) {
+        return { ok: false, reason: "invalid-path", error };
+      }
+      if (!isPathInside(root, lexical)) return { ok: false, reason: "escape" };
+
+      let target;
+      try {
+        target = realpathSync.native(lexical);
+      } catch (error) {
+        return { ok: false, reason: error?.code === "ENOENT" ? "not-found" : "unreadable", error };
+      }
+      if (!isPathInside(root, target)) return { ok: false, reason: "escape" };
+
+      return { ok: true, path: target };
+    },
+  };
+}
+
+// Resolve one existing repo-relative path without allowing lexical traversal or
+// symlink/junction escapes. Callers get a reason instead of an exception so MCP
+// tools can refuse the read without exposing host filesystem details.
+export function resolveRepoPath(repoRoot, candidate) {
+  return createRepoBoundary(repoRoot).resolve(candidate);
+}