weavatrix 0.3.13 → 1.0.0

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

@@ -1,200 +0,0 @@
-import {findSeeds, rawGraph} from './graph-context.mjs'
-import {toolResult} from './tool-result.mjs'
-import {expandTaskQuery, retrieveTaskContext} from '../analysis/task-retrieval.js'
-import {extractCallArgumentEvidence} from '../analysis/data-flow-evidence.js'
-import {runAllowedTests, validateTestRequests} from '../analysis/allowed-test-runner.js'
-import {compareDuplicateGroups} from '../analysis/duplicate-groups.js'
-import {buildGraphAtGitRef} from '../analysis/git-ref-graph.js'
-import {diffGraphs, formatGraphDiff} from './graph-diff.mjs'
-
-const richResult = (value) => value?.__weavatrixToolResult === true ? value.result : null
-const normalizeFile = (value) => String(value || '').replace(/\\/g, '/')
-const changedFilesOf = (impact) => [...new Set((impact?.changes || []).flatMap((change) => [change.path, change.oldPath, change.newPath]).map(normalizeFile).filter((file) => file && file !== '(diff unavailable)'))]
-const targetTests = (impact) => [...new Set([
-  ...(impact?.testEvidence?.changedFiles || []).map((item) => item.staticTestReachability?.test),
-  ...(impact?.blastRadius?.nodes || []).map((node) => node.testEvidence?.staticTestReachability?.test),
-].filter(Boolean))].slice(0, 30)
-
-function testCoverage(proof, requests, suggested) {
-  if (!suggested.length) return {state: 'NOT_APPLICABLE', covered: [], missing: []}
-  if (proof.state !== 'PASS') return {state: 'PENDING', covered: [], missing: suggested}
-  if ((requests || []).some((request) => request?.script === 'test' && (!request.args || !request.args.length))) {
-    return {state: 'COMPLETE', kind: 'full-test-script', covered: suggested, missing: []}
-  }
-  const args = (requests || []).flatMap((request) => request?.args || []).map(normalizeFile)
-  const covered = suggested.filter((file) => args.some((arg) => arg === file || arg.endsWith(`/${file}`)))
-  return {state: covered.length === suggested.length ? 'COMPLETE' : 'PARTIAL', kind: 'explicit-test-paths', covered, missing: suggested.filter((file) => !covered.includes(file))}
-}
-
-function graphProof(diff) {
-  const runtimeCycles = diff?.cycles?.runtime?.introduced || []
-  return {
-    state: runtimeCycles.length ? 'BLOCKED' : diff.schemaMigration ? 'UNKNOWN' : 'PASS',
-    ...(diff.schemaMigration ? {reason: 'graph extractor/schema versions differ, so structural ratchets are not comparable'} : {}),
-    summary: formatGraphDiff(diff),
-    counts: {
-      nodesAdded: diff.nodes.added.length, nodesRemoved: diff.nodes.removed.length,
-      edgesAdded: diff.edges.added, edgesRemoved: diff.edges.removed,
-      moduleDependenciesAdded: diff.moduleEdges.added.length, orphaned: diff.orphaned.length,
-      runtimeCyclesIntroduced: runtimeCycles.length,
-    },
-    runtimeCycles: runtimeCycles.slice(0, 20), moduleDependenciesAdded: diff.moduleEdges.added.slice(0, 20),
-    orphaned: diff.orphaned.slice(0, 20), schemaMigration: diff.schemaMigration,
-  }
-}
-
-async function baselineProof(ctx, baseRef, currentGraph) {
-  const mode = ['full', 'no-tests', 'tests-only'].includes(currentGraph?.graphBuildMode) ? currentGraph.graphBuildMode : 'full'
-  const built = await buildGraphAtGitRef(ctx.repoRoot, baseRef, {mode})
-  if (!built.ok) return {state: 'UNKNOWN', reason: built.error}
-  return {...graphProof(diffGraphs(built.graph, currentGraph)), baseline: {ref: built.ref, commit: built.commit}}
-}
-
-function apiState(result) {
-  if (!result || result.status !== 'COMPLETE' || result.completeness?.complete !== true) return 'UNKNOWN'
-  if (['HTTP_METHOD_MISMATCH', 'CLIENTS_AT_RISK_WITH_METHOD_MISMATCHES'].includes(result.verdict?.code)) return 'BLOCKED'
-  return 'UNKNOWN'
-}
-
-function architectureState(result) {
-  if (!result || result.state === 'NOT_CONFIGURED' || result.state === 'ERROR') return 'UNKNOWN'
-  if (!result.verification) return result.state === 'READY' ? 'PASS' : 'UNKNOWN'
-  return result.verification.new?.length || String(result.verification.status).toUpperCase() === 'FAIL' ? 'BLOCKED' : 'PASS'
-}
-
-function exactUsageLines(contexts, g) {
-  if (!contexts.length) return []
-  return contexts.map((context) => {
-    const node = g.byId.get(String(context.symbol || context.definition?.id || ''))
-    const label = String(context.definition?.label || node?.label || context.symbol || 'symbol')
-    if (context.status !== 'OK') return `Exact usage: ${label} — unavailable (${context.status || 'UNKNOWN'}).`
-    const exact = context.evidence?.state === 'EXACT'
-    const occurrences = Number(context.references?.occurrences) || 0
-    const files = Number(context.references?.files) || 0
-    const inbound = Array.isArray(context.inbound?.shown) ? context.inbound.shown.slice(0, 3) : []
-    const callers = inbound.map((item) => `${item.label || item.id}${item.file ? ` [${item.file}]` : ''}`).join(', ')
-    return `${exact ? 'Exact usage' : 'Bounded usage'}: ${label} — ${occurrences} reference occurrence(s)${files ? ` in ${files} file(s)` : ''}; ${Number(context.inbound?.total) || 0} inbound container(s)${callers ? `: ${callers}` : ''}.`
-  })
-}
-
-function decide({phase, impact, graph, architecture, duplicates, api, tests, suggestedTests, testCoverageState}) {
-  if (phase === 'plan') return tests.state === 'BLOCKED'
-    ? {verdict: 'BLOCKED', blockers: [`targeted test plan was rejected: ${tests.reason || 'invalid request'}`], unknowns: []}
-    : {verdict: 'UNKNOWN', blockers: [], unknowns: ['verification has not run; apply the edit and call verified_change with phase=verify']}
-  if (impact.status === 'COMPLETE' && !impact.changes?.length) return {verdict: 'PASS', blockers: [], unknowns: []}
-  const blockers = [], unknowns = []
-  if (impact.status !== 'COMPLETE') unknowns.push('change impact is partial or has unmapped evidence')
-  if (graph.state === 'BLOCKED') blockers.push('the change introduces a runtime dependency cycle')
-  if (graph.state === 'UNKNOWN') unknowns.push(`Git graph baseline is unavailable: ${graph.reason || 'unknown reason'}`)
-  if (architecture.state === 'BLOCKED') blockers.push('new architecture-contract violations were found')
-  if (architecture.state === 'UNKNOWN') unknowns.push('architecture contract is not configured or verification is incomplete')
-  if (duplicates.state === 'BLOCKED') blockers.push('new duplicate groups intersect the changed files')
-  if (duplicates.state === 'UNKNOWN') unknowns.push(`duplicate ratchet is incomplete: ${duplicates.reason || 'health capability unavailable'}`)
-  if (api.state === 'BLOCKED') blockers.push('cross-repository API evidence contains HTTP method mismatches')
-  if (api.state === 'UNKNOWN') unknowns.push(`API contract evidence is incomplete: ${api.reason || 'no bounded proof'}`)
-  if (tests.state === 'FAIL' || tests.state === 'BLOCKED') {
-    const failed = (tests.results || []).filter((result) => result.status !== 'PASS').map((result) => `${result.script} (${result.status}${result.exitCode == null ? '' : `, exit ${result.exitCode}`})`)
-    blockers.push(`targeted tests failed or were rejected: ${tests.reason || failed.join(', ') || 'unknown failure'}`)
-  }
-  if (tests.state === 'DISABLED') unknowns.push('targeted test execution was requested but runtime permission is disabled')
-  if (tests.state === 'NOT_REQUESTED' && suggestedTests.length) unknowns.push('affected tests were identified but no allowlisted package test was requested')
-  if (tests.state === 'PASS' && testCoverageState.state === 'PARTIAL') unknowns.push(`targeted test run did not cover ${testCoverageState.missing.length} suggested test path(s)`)
-  return {verdict: blockers.length ? 'BLOCKED' : unknowns.length ? 'UNKNOWN' : 'PASS', blockers, unknowns}
-}
-
-export async function tVerifiedChange(g, args = {}, ctx = {}, tools = {}, permissions = {}) {
-  const phase = args.phase === 'verify' ? 'verify' : 'plan'
-  const currentGraph = rawGraph(ctx)
-  const impactValue = await tools.impact(g, {base: args.base_ref, diff: args.diff, files: args.files, depth: args.impact_depth, max_nodes: args.max_impact_nodes}, ctx)
-  const impact = richResult(impactValue) || {status: 'PARTIAL', changes: [], seeds: {ids: []}, blastRadius: {nodes: []}}
-  const changedFiles = changedFilesOf(impact)
-  const retrieval = retrieveTaskContext(g, {
-    task: args.task, semanticSeeds: findSeeds(g, expandTaskQuery(args.task), 12, {repoRoot: ctx.repoRoot}),
-    changedSeedIds: impact.seeds?.ids, maxSymbols: args.max_symbols, repoRoot: ctx.repoRoot,
-  })
-
-  let contexts = []
-  if (permissions.source) contexts = await Promise.all(retrieval.selected.map(async (symbol) => {
-    const value = await tools.context(g, {label: symbol.id, precision: args.precision, max_related: 8, max_source_files: 3, context_lines: 4}, ctx, tools.inspect)
-    const result = richResult(value)
-    return result ? {symbol: symbol.id, status: result.status, definition: result.definition, evidence: result.evidence, references: result.references, inbound: result.inbound, outbound: result.outbound, reExports: result.reExports, source: result.source} : {symbol: symbol.id, status: 'UNKNOWN'}
-  }))
-  const dataFlow = permissions.source ? extractCallArgumentEvidence({
-      graph: g, repoRoot: ctx.repoRoot, seedIds: retrieval.selected.map((item) => item.id),
-      depth: Math.max(1, Math.min(3, Number(args.data_flow_depth) || 2)),
-      maxEdges: Math.max(1, Math.min(60, Number(args.max_data_flow_edges) || 30)),
-    })
-    : {model: 'bounded call-argument-to-parameter evidence (not CFG or taint analysis)', status: 'UNAVAILABLE', reason: 'source capability is not enabled', edges: [], unsupportedEdges: 0, capped: false}
-  const suggestedTests = targetTests(impact)
-  const requestedTests = Array.isArray(args.tests) ? args.tests : []
-  let testProof
-  if (!requestedTests.length) {
-    testProof = {state: 'NOT_REQUESTED', reason: 'no package scripts were requested', plan: [], results: []}
-  } else if (args.run_tests !== true) {
-    testProof = await runAllowedTests(ctx.repoRoot, requestedTests, {enabled: false, timeoutMs: args.test_timeout_ms})
-  } else if (phase === 'verify') {
-    testProof = await runAllowedTests(ctx.repoRoot, requestedTests, {enabled: true, timeoutMs: args.test_timeout_ms})
-  } else {
-    const checkedTests = validateTestRequests(ctx.repoRoot, requestedTests)
-    testProof = {state: checkedTests.ok ? 'PLANNED' : 'BLOCKED', reason: checkedTests.reason, plan: checkedTests.tests || [], results: []}
-  }
-  const testCoverageState = testCoverage(testProof, args.tests || [], suggestedTests)
-
-  const architectureValue = phase === 'verify'
-    ? (permissions.health ? tools.verifyArchitecture(g, {}, ctx) : null)
-    : tools.prepareChange(g, {intent: args.task, files: changedFiles}, ctx)
-  const architectureResult = richResult(architectureValue)
-  const architecture = {state: architectureState(architectureResult), evidence: architectureResult}
-  const baseRef = String(args.base_ref || 'HEAD').trim()
-  const graph = phase === 'verify' ? await baselineProof(ctx, baseRef, currentGraph) : {state: 'PLANNED', baseline: baseRef}
-
-  const duplicateRatchetEnabled = args.duplicate_ratchet !== false
-  let duplicates
-  if (!duplicateRatchetEnabled) {
-    duplicates = {state: 'SKIPPED', enabled: false, reason: 'duplicate ratchet disabled'}
-  } else if (phase !== 'verify') {
-    duplicates = {state: 'PLANNED', enabled: true, reason: 'duplicate ratchet runs during verify phase'}
-  } else {
-    duplicates = permissions.health
-      ? {enabled: true, ...await compareDuplicateGroups({repoRoot: ctx.repoRoot, graphPath: ctx.graphPath, currentGraph, baseRef, changedFiles, args: {mode: 'renamed', min_similarity: 80, min_tokens: 50}})}
-      : {state: 'UNKNOWN', enabled: true, reason: 'health capability is not enabled'}
-  }
-
-  let api = {state: 'SKIPPED', reason: 'no api_contract scope was requested'}
-  if (args.api_contract) {
-    if (!permissions.crossrepo) api = {state: 'UNKNOWN', reason: 'crossrepo capability is not enabled'}
-    else {
-      const result = richResult(await tools.traceApi(g, {
-        ...args.api_contract, changed_files: args.api_contract.changed_files || changedFiles,
-        max_endpoints: Math.min(100, Number(args.api_contract.max_endpoints) || 100),
-        max_matches: Math.min(500, Number(args.api_contract.max_matches) || 500),
-        max_affected_files: Math.min(100, Number(args.api_contract.max_affected_files) || 100),
-        top_n: Math.min(10, Number(args.api_contract.top_n) || 10),
-      }, ctx))
-      api = {state: apiState(result), evidence: result}
-    }
-  }
-
-  const decision = decide({phase, impact, graph, architecture, duplicates, api, tests: testProof, suggestedTests, testCoverageState})
-  if (!permissions.source && retrieval.selected.length) decision.unknowns.push('source capability is disabled; exact LSP/source edit contexts were not collected')
-  if (phase === 'verify' && contexts.some((item) => item.status !== 'OK' || item.evidence?.state !== 'EXACT' || item.references?.capped)) {
-    decision.unknowns.push('one or more exact edit contexts are incomplete')
-  }
-  if (phase === 'verify' && args.diff) decision.unknowns.push('a supplied diff was classified, but equivalence between that patch and the active graph is not proven; verify on a checked-out change without diff')
-  if (decision.verdict === 'PASS' && decision.unknowns.length) decision.verdict = 'UNKNOWN'
-  const result = {
-    schemaVersion: 'weavatrix.verified-change.v1', verdict: decision.verdict, phase, task: String(args.task),
-    blockers: decision.blockers, unknowns: decision.unknowns,
-    retrieval, editContexts: contexts, dataFlow, changeImpact: impact, graphBaseline: graph,
-    architecture, duplicates, apiContract: api, tests: {...testProof, suggestedFiles: suggestedTests, coverage: testCoverageState},
-  }
-  const text = [
-    `${decision.verdict} — verified_change ${phase}`, `Task: ${String(args.task).slice(0, 500)}`,
-    `Change: ${changedFiles.length} file(s), ${impact.seeds?.ids?.length || 0} exact seed(s), blast radius ${impact.blastRadius?.impacted || 0}.`,
-    `Edit context: ${retrieval.selected.length} symbol(s); ${contexts.length} exact bundle(s); data-flow ${dataFlow.status} (${dataFlow.edges.length} call edge(s)).`,
-    ...exactUsageLines(contexts, g),
-    `Ratchets: graph ${graph.state}; architecture ${architecture.state}; duplicates ${duplicates.state}; API ${api.state}; tests ${testProof.state}.`,
-    ...decision.blockers.map((item) => `BLOCKER: ${item}`), ...decision.unknowns.map((item) => `UNKNOWN: ${item}`),
-  ].join('\n')
-  return toolResult(text, result, {completeness: {status: decision.verdict === 'UNKNOWN' ? 'PARTIAL' : 'COMPLETE'}})
-}

package/src/mcp-rg.mjs

@@ -1,50 +0,0 @@
-import { readdirSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { createRequire } from 'node:module'
-import { runCommandSync } from './process.js'
-
-const rgInInstall = (base) => [
-    join(base, 'resources', 'app', 'node_modules', '@vscode', 'ripgrep', 'bin', 'rg.exe'),
-    join(base, 'resources', 'app', 'node_modules', '@vscode', 'ripgrep-universal', 'bin', 'win32-x64', 'rg.exe'),
-]
-
-function editorRgCandidates() {
-    if (process.platform !== 'win32') return []
-    const local = process.env.LOCALAPPDATA || ''
-    const pf = process.env.PROGRAMFILES || ''
-    const roots = [local && join(local, 'Programs', 'Microsoft VS Code'), local && join(local, 'Programs', 'cursor'), pf && join(pf, 'Microsoft VS Code')].filter(Boolean)
-    const out = []
-    for (const root of roots) {
-        if (!existsSync(root)) continue
-        out.push(...rgInInstall(root))
-        try {
-            for (const d of readdirSync(root, {withFileTypes: true})) if (d.isDirectory()) out.push(...rgInInstall(join(root, d.name)))
-        } catch { /* optional editor install probe */ }
-    }
-    return out
-}
-
-export function createRgResolver(selfDir) {
-    let rgPath
-    return function resolveRg() {
-        if (rgPath !== undefined) return rgPath
-        rgPath = null
-        const env = (process.env.WEAVATRIX_RG_CMD || '').replace(/^"|"$/g, '')
-        if (env && existsSync(env)) return (rgPath = env)
-        try {
-            const {rgPath: bundledRg} = createRequire(import.meta.url)('@vscode/ripgrep')
-            if (bundledRg && existsSync(bundledRg)) return (rgPath = bundledRg)
-        } catch { /* optional bundled ripgrep module */ }
-        try {
-            const unpackedRg = join(selfDir, '..', '..', 'node_modules', '@vscode', 'ripgrep', 'bin', process.platform === 'win32' ? 'rg.exe' : 'rg')
-            if (existsSync(unpackedRg)) return (rgPath = unpackedRg)
-        } catch { /* optional packaged ripgrep path */ }
-        for (const c of editorRgCandidates()) if (existsSync(c)) return (rgPath = c)
-        try {
-            const probe = runCommandSync(process.platform === 'win32' ? 'where' : 'which', ['rg'], {timeout: 3000})
-            const p = probe.status === 0 ? probe.stdout.split(/\r?\n/)[0].trim() : ''
-            if (p && existsSync(p)) return (rgPath = p)
-        } catch { /* optional PATH probe */ }
-        return rgPath
-    }
-}

package/src/mcp-runtime.mjs

@@ -1,2 +0,0 @@
-export {startMcpServer} from './mcp-server.mjs'
-export {DEFAULT_CAPS} from './mcp/catalog.mjs'

package/src/mcp-server.mjs

@@ -1,298 +0,0 @@
-// Weavatrix MCP stdio entry point; implementations and extension composition live in src/mcp/*.
-// Spawned by Claude Code / Codex as a plain Node child (node mcp-server.mjs <graph.json> <repoRoot>).
-// Speaks newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio transport).
-//
-// .mjs on purpose: guarantees ESM parsing regardless of the nearest package.json. Runtime analyzers
-// resolve only dependencies bundled with Weavatrix: web-tree-sitter grammars for graph builds and the
-// pinned TypeScript language server for bounded JS/TS semantic evidence. Repository packages/scripts
-// are never executed to provide either analyzer.
-//
-// STDOUT is the protocol channel — nothing but JSON-RPC frames may be written there. All diagnostics
-// 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 process from 'node:process'
-import {resolve} from 'node:path'
-import {pathToFileURL} from 'node:url'
-import {loadGraph} from './mcp/graph-context.mjs'
-import {createStalenessNoticeGate} from './mcp/staleness-notice.mjs'
-import {normalizeToolResult} from './mcp/tool-result.mjs'
-import {runtimeVersionStatus, staleRuntimeMessage} from './mcp/runtime-version.mjs'
-import {createAutoRefresh} from './mcp/server/auto-refresh.mjs'
-import {createShutdownController} from './mcp/server/shutdown.mjs'
-import {
-    hotCatalogVersion as hotVersion, loadServerCatalog as loadCatalog, PACKAGE_JSON_PATH,
-    PACKAGE_VERSION as PKG_VERSION, resolveServerTarget, SERVER_INFO,
-} from './mcp/server/runtime-config.mjs'
-
-// version comes from package.json so serverInfo can never drift from the published package again
-const DEFAULT_PROTOCOL = '2024-11-05'
-const log = (...a) => process.stderr.write(`[weavatrix] ${a.join(' ')}\n`)
-
-// ---- hot reload of tool implementations -----------------------------------------------------------
-// Node caches modules at spawn, so edits to the tool code would otherwise be invisible until the MCP
-// client reconnects. Before each tools/list|call we stat the hot-reloadable files (HOT_FILES); when
-// any changed on disk we re-import them through catalog.loadHotApi with a cache-busting version and
-// 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.
-export async function startMcpServer({
-    argv = process.argv,
-    defaultCapabilities,
-    loadExtensions = async () => [],
-    packageJsonPath = PACKAGE_JSON_PATH,
-    packageVersion = PKG_VERSION,
-    serverInfo = SERVER_INFO,
-} = {}) {
-    const target = resolveServerTarget(argv, log)
-    const GRAPH_PATH = target.graphPath
-    const REPO_ROOT = target.repoRoot
-    const CAPS_ARG = target.capabilities ?? defaultCapabilities
-    let catalog = await loadCatalog()
-    let extensions = await loadExtensions({version: 0})
-    let api = await catalog.loadHotApi(0, CAPS_ARG, {extensions})
-    const runtimeInfo = () => ({
-        ...runtimeVersionStatus({runningVersion: packageVersion, packageJsonPath}),
-        profile: api.profile || 'custom',
-        capabilities: [...api.caps],
-        toolCount: api.tools.length,
-        ...(api.extensions.items.length ? {extensions: api.extensions.items} : {}),
-    })
-    const runtimeInstructions = () => {
-        const runtime = runtimeInfo()
-        const stale = runtime.staleRuntime
-            ? ` ${staleRuntimeMessage(runtime)}${runtime.staleRuntimeAllowed ? ' Development override is active.' : ''}`
-            : ''
-        return `Weavatrix ${runtime.version}; diskVersion=${runtime.diskVersion || 'unavailable'}; profile=${runtime.profile}; tools=${runtime.toolCount}; capabilities=${runtime.capabilities.join(',') || '(none)'}.${stale} If this differs from the client-visible tool list, reconnect the MCP client to discard its cached schema.`
-    }
-    let graph = null
-    let graphError = null
-    // ctx owns the CURRENT target: rebuild_graph reloads it, open_repo retargets graphPath/repoRoot
-    // at runtime. loadInto always reads ctx.graphPath so both paths share one loader.
-    const ctx = {graphPath: GRAPH_PATH, repoRoot: REPO_ROOT, reload: null, runtime: runtimeInfo(), extensions: api.extensions}
-    const loadInto = () => { graph = loadGraph(ctx.graphPath, {repoRoot: ctx.repoRoot}); graphError = null; return graph }
-    ctx.reload = () => { api.resetStalenessCache(); try { return loadInto() } catch (e) { graphError = e.message; return null } }
-    try {
-        if (!ctx.graphPath) throw new Error('no graph.json path given (argv[2])')
-        loadInto()
-        log(`loaded ${graph.nodes.length} nodes / ${graph.links.length} edges from ${ctx.graphPath}`)
-    } catch (e) {
-        graphError = e.message
-        log(`failed to load graph: ${e.message}`)
-    }
-    log(`repo root: ${REPO_ROOT || '(none — source/action tools disabled)'}`)
-    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 shutdown = createShutdownController({log, targetMutation: () => targetMutation})
-    const autoRefresh = createAutoRefresh(() => api)
-    const send = (msg) => {
-        // A request that was already running when the client disconnected may complete during the
-        // bounded drain. Do not write a late reply into a closed protocol pipe.
-        if (shutdown.isShuttingDown() || process.stdout.destroyed || !process.stdout.writable) return false
-        try {
-            return process.stdout.write(JSON.stringify(msg) + '\n')
-        } catch (error) {
-            if (error?.code === 'EPIPE' || error?.code === 'ERR_STREAM_DESTROYED') return false
-            throw error
-        }
-    }
-    const reply = (id, result) => send({jsonrpc: '2.0', id, result})
-    const fail = (id, code, message, data) => send({jsonrpc: '2.0', id, error: {code, message, ...(data ? {data} : {})}})
-
-    const requestShutdown = shutdown.request
-    process.stdout.on('error', (error) => {
-        if (error?.code === 'EPIPE' || error?.code === 'ERR_STREAM_DESTROYED') {
-            void requestShutdown('stdout disconnected')
-            return
-        }
-        log(`stdout error: ${error.stack || error.message}`)
-        void requestShutdown('stdout error', 1)
-    })
-
-    let loadedVersion = hotVersion(catalog.HOT_FILES)
-    let lastFailedVersion = 0
-    const maybeHotReload = async () => {
-        const v = hotVersion(catalog.HOT_FILES)
-        if (v <= loadedVersion || v === lastFailedVersion) return
-        try {
-            const nextCatalog = await loadCatalog(v)
-            const nextExtensions = await loadExtensions({version: v})
-            const nextApi = await nextCatalog.loadHotApi(v, CAPS_ARG, {extensions: nextExtensions})
-            catalog = nextCatalog
-            api = nextApi
-            extensions = nextExtensions
-            ctx.runtime = runtimeInfo()
-            ctx.extensions = api.extensions
-            loadedVersion = v
-            log(`hot-reloaded tool implementations from changed source (${api.tools.length} tools)`)
-            send({jsonrpc: '2.0', method: 'notifications/tools/list_changed'})
-        } catch (e) {
-            lastFailedVersion = v // remember the broken version so we don't retry it every call
-            log(`hot-reload failed, keeping current tools: ${e.message}`)
-        }
-    }
-
-    const handle = async (msg) => {
-        const {id, method, params} = msg
-        const isNotification = id === undefined || id === null
-        if (shutdown.isShuttingDown()) {
-            if (!isNotification) fail(id, -32000, 'MCP server is shutting down')
-            return
-        }
-        if (method === 'initialize' || method === 'tools/list' || method === 'tools/call') {
-            const runtime = runtimeInfo()
-            ctx.runtime = runtime
-            if (runtime.staleRuntime && !runtime.staleRuntimeAllowed) {
-                if (!isNotification) fail(id, -32001, staleRuntimeMessage(runtime), {'weavatrix/runtime': runtime})
-                return
-            }
-        }
-        if (method === 'initialize') {
-            if (params?.protocolVersion) protocolVersion = String(params.protocolVersion)
-            return reply(id, {
-                protocolVersion, capabilities: {tools: {listChanged: true}}, serverInfo,
-                instructions: runtimeInstructions(), _meta: {'weavatrix/runtime': runtimeInfo()},
-            })
-        }
-        if (method === 'notifications/initialized' || method === 'initialized') return
-        if (method === 'ping') return reply(id, {})
-        if (method === 'tools/list') {
-            await maybeHotReload()
-            if (shutdown.isShuttingDown()) return
-            return reply(id, {
-                tools: api.tools.map(({name, description, inputSchema, outputSchema}) => ({name, description, inputSchema, outputSchema})),
-                _meta: {'weavatrix/runtime': runtimeInfo()},
-            })
-        }
-        if (method === 'tools/call') {
-            await maybeHotReload()
-            // EOF can arrive while the hot-reload import is pending. Do not enqueue a graph mutation
-            // after requestShutdown captured the mutation chain it is responsible for draining.
-            if (shutdown.isShuttingDown()) return
-            const tool = api.byName.get(params?.name)
-            if (!tool) return reply(id, {content: [{type: 'text', text: `Unknown tool: ${params?.name}`}], isError: true})
-            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 () => {
-                const startedAt = performance.now()
-                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}`
-                    }
-                    const structuredBytes = normalized.structured ? Buffer.byteLength(JSON.stringify(normalized.structured)) : 0
-                    const textBytes = Buffer.byteLength(text)
-                    const durationMs = Math.max(0, performance.now() - startedAt)
-                    const response = {
-                        content: [{type: 'text', text}],
-                        _meta: {
-                            'weavatrix/metrics': {
-                                schemaVersion: 'weavatrix.metrics.v1',
-                                durationMs: Math.round(durationMs * 10) / 10,
-                                textBytes,
-                                structuredBytes,
-                                estimatedOutputTokens: Math.ceil((textBytes + structuredBytes) / 4),
-                                graphFreshness: staleLine ? 'stale' : (refresh?.error ? 'stale' : 'fresh'),
-                                graphUpdate: refresh?.kind || 'none',
-                                graphRevision: refresh?.revision || callGraph?.graphRevision || null,
-                                cache: refreshesGraph ? (refresh?.kind === 'none' ? 'graph-hit' : 'graph-refreshed') : 'not-applicable',
-                            },
-                        },
-                    }
-                    if (normalized.structured) response.structuredContent = normalized.structured
-                    return reply(id, response)
-                } catch (e) {
-                    log(`tool ${params?.name} threw: ${e.stack || e.message}`)
-                    const text = `Tool error: ${e.message}`
-                    return reply(id, {
-                        content: [{type: 'text', text}], isError: true,
-                        _meta: {'weavatrix/metrics': {
-                            schemaVersion: 'weavatrix.metrics.v1', durationMs: Math.round(Math.max(0, performance.now() - startedAt) * 10) / 10,
-                            textBytes: Buffer.byteLength(text), structuredBytes: 0,
-                            estimatedOutputTokens: Math.ceil(Buffer.byteLength(text) / 4), graphFreshness: 'unknown',
-                            graphUpdate: 'none', graphRevision: graphSnapshot?.graphRevision || null, cache: 'not-applicable',
-                        }},
-                    })
-                }
-            }
-            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}`)
-    }
-
-    let buf = ''
-    process.stdin.setEncoding('utf8')
-    process.stdin.on('data', (chunk) => {
-        if (shutdown.isShuttingDown()) return
-        buf += chunk
-        let nl
-        while ((nl = buf.indexOf('\n')) >= 0) {
-            const line = buf.slice(0, nl).trim()
-            buf = buf.slice(nl + 1)
-            if (!line) continue
-            let msg
-            try {
-                msg = JSON.parse(line)
-            } catch {
-                log(`bad JSON line: ${line.slice(0, 120)}`)
-                continue
-            }
-            // handle is async (rebuild_graph awaits a build) → catch rejections, not just sync throws
-            Promise.resolve().then(() => handle(msg)).catch((e) => {
-                log(`handler error: ${e.stack || e.message}`)
-                if (msg?.id != null) fail(msg.id, -32603, `Internal error: ${e.message}`)
-            })
-        }
-    })
-    process.stdin.on('end', () => { void requestShutdown('stdin EOF') })
-    process.on('SIGTERM', () => { void requestShutdown('SIGTERM') })
-    process.on('SIGINT', () => { void requestShutdown('SIGINT') })
-    log('ready')
-}
-
-// Guard: hot-reload re-imports of tool modules never touch this entry, but keep the start guard so a
-// stray re-import of the entry itself can never spawn a second stdio loop.
-const directEntry = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
-if (directEntry && !globalThis.__weavatrixMcpStarted) {
-    globalThis.__weavatrixMcpStarted = true
-    startMcpServer()
-}