weavatrix 0.2.8 → 0.2.9

package/src/mcp/evidence-snapshot.package-graph.mjs

@@ -3,7 +3,7 @@ import {readFileSync, statSync} from 'node:fs'
 import {createRepoBoundary} from '../repo-path.js'
 import {CAPS, STATE, compareText, safeToken} from './evidence-snapshot.common.mjs'
 
-const LOCKFILES = ['npm-shrinkwrap.json', 'package-lock.json']
+const LOCKFILES = ['npm-shrinkwrap.json', 'package-lock.json', 'bun.lock']
 const MAX_LOCKFILE_BYTES = 64 * 1024 * 1024
 const MAX_PACKAGE_RECORDS = 50_000
 const MAX_DEPENDENCY_DECLARATIONS = 200_000
@@ -191,6 +191,10 @@ function parseLock(lock, lockfile) {
     if (declarationLimitReached) reasons.push('LOCKFILE_DEPENDENCY_DECLARATION_LIMIT_REACHED')
     if (declarations.unresolved > 0) reasons.push('UNRESOLVED_LOCKFILE_DEPENDENCIES')
 
+    return finalizeGraph({externalNodes, edgeMap, declarations, reasons, lockfile, lockfileVersion})
+}
+
+function finalizeGraph({externalNodes, edgeMap, declarations, reasons, lockfile, lockfileVersion}) {
     const allNodes = [...externalNodes.values()].sort((a, b) =>
         Number(b.direct) - Number(a.direct) || compareText(a.name, b.name) ||
         compareText(a.version, b.version) || compareText(a.id, b.id))
@@ -223,6 +227,255 @@ function parseLock(lock, lockfile) {
     }
 }
 
+// Bun >= 1.2 writes a text lockfile (bun.lock) as JSONC: JSON plus comments and
+// trailing commas. parseJsonc strips both (outside of strings) with no new deps.
+function parseJsonc(text) {
+    const source = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+    const out = []
+    let i = 0
+    const length = source.length
+    const skipComment = (index) => {
+        if (source[index] !== '/') return index
+        if (source[index + 1] === '/') {
+            let cursor = index + 2
+            while (cursor < length && source[cursor] !== '\n') cursor++
+            return cursor
+        }
+        if (source[index + 1] === '*') {
+            let cursor = index + 2
+            while (cursor < length && !(source[cursor] === '*' && source[cursor + 1] === '/')) cursor++
+            return Math.min(cursor + 2, length)
+        }
+        return index
+    }
+    while (i < length) {
+        const char = source[i]
+        if (char === '"') {
+            const start = i
+            i++
+            while (i < length && source[i] !== '"') i += source[i] === '\\' ? 2 : 1
+            i = Math.min(i + 1, length)
+            out.push(source.slice(start, i))
+            continue
+        }
+        if (char === '/') {
+            const next = skipComment(i)
+            if (next !== i) { i = next; continue }
+        }
+        if (char === ',') {
+            let ahead = i + 1
+            while (ahead < length) {
+                if (/\s/.test(source[ahead])) { ahead++; continue }
+                const next = skipComment(ahead)
+                if (next !== ahead) { ahead = next; continue }
+                break
+            }
+            if (ahead < length && (source[ahead] === '}' || source[ahead] === ']')) { i++; continue }
+        }
+        out.push(char)
+        i++
+    }
+    return JSON.parse(out.join(''))
+}
+
+// bun.lock package keys are slash-joined chains of package names describing the
+// hoisted install position, e.g. "make-dir/semver" (semver as resolved for
+// make-dir). Scoped names keep their own slash: "@scope/pkg/dep".
+function bunKeySegments(key) {
+    if (typeof key !== 'string' || key.length === 0 || key.length > 4096 || /[\u0000-\u001f\u007f]/.test(key)) return null
+    const parts = key.split('/')
+    const segments = []
+    for (let index = 0; index < parts.length; index++) {
+        let segment = parts[index]
+        if (segment.startsWith('@')) {
+            if (index + 1 >= parts.length) return null
+            segment = `${segment}/${parts[++index]}`
+        }
+        if (segment.length > 256 || !PACKAGE_NAME.test(segment)) return null
+        segments.push(segment)
+    }
+    return segments
+}
+
+// Entry shape: "key": ["name@version", registry, {dependencies, peerDependencies,
+// optionalPeers, ...}, integrity]. Workspace members resolve to "name@workspace:path".
+function bunPackageRecord(entry) {
+    if (!Array.isArray(entry) || typeof entry[0] !== 'string' || entry[0].length > 1024) return null
+    const at = entry[0].lastIndexOf('@')
+    if (at <= 0) return null
+    const name = entry[0].slice(0, at)
+    if (name.length > 256 || !PACKAGE_NAME.test(name)) return null
+    const rawVersion = entry[0].slice(at + 1)
+    const meta = entry.slice(1).find((value) => value && typeof value === 'object' && !Array.isArray(value)) || {}
+    return {name, rawVersion, workspace: rawVersion.startsWith('workspace:'), meta}
+}
+
+// Adapts a bun dependency map ({dependencies, devDependencies, optionalDependencies,
+// peerDependencies, optionalPeers: [names]}) to the npm record shape consumed by
+// dependencyDeclarations, so declaration kinds and precedence stay identical.
+function bunDeclarationRecord(meta) {
+    if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return {}
+    const peerDependenciesMeta = {}
+    if (Array.isArray(meta.optionalPeers)) {
+        for (const name of meta.optionalPeers) {
+            if (typeof name === 'string') peerDependenciesMeta[name] = {optional: true}
+        }
+    }
+    return {
+        dependencies: meta.dependencies,
+        devDependencies: meta.devDependencies,
+        optionalDependencies: meta.optionalDependencies,
+        peerDependencies: meta.peerDependencies,
+        peerDependenciesMeta,
+    }
+}
+
+// Mirrors bun resolution: the most specific override key wins ("a/b/name"),
+// falling back segment by segment to the hoisted top-level key ("name").
+function resolveBunDependency(sourceSegments, name, records) {
+    for (let depth = sourceSegments.length; depth >= 0; depth--) {
+        const key = [...sourceSegments.slice(0, depth), name].join('/')
+        const record = records.get(key)
+        if (record) return {key, record}
+    }
+    return null
+}
+
+// bun.lock does not persist npm's per-package dev/optional/peer flags, so they are
+// approximated from graph reachability the same way npm derives them: a package is
+// dev when unreachable from the root without dev edges, optional (or peer) when
+// unreachable without optional (or peer) edges.
+function applyBunReachabilityFlags(nodes, edges) {
+    const adjacency = new Map()
+    for (const edge of edges) {
+        if (!adjacency.has(edge.from)) adjacency.set(edge.from, [])
+        adjacency.get(edge.from).push(edge)
+    }
+    const reach = (excluded) => {
+        const seen = new Set(['(root)'])
+        const queue = ['(root)']
+        while (queue.length) {
+            for (const edge of adjacency.get(queue.pop()) || []) {
+                if (excluded.has(edge.kind) || seen.has(edge.to)) continue
+                seen.add(edge.to)
+                queue.push(edge.to)
+            }
+        }
+        return seen
+    }
+    const withoutDev = reach(new Set(['dev']))
+    const withoutOptional = reach(new Set(['optional', 'optional-peer']))
+    const withoutPeer = reach(new Set(['peer', 'optional-peer']))
+    for (const node of nodes) {
+        node.dev = !withoutDev.has(node.id)
+        node.optional = !withoutOptional.has(node.id)
+        node.peer = !withoutPeer.has(node.id)
+    }
+}
+
+function parseBunLock(lock, lockfile) {
+    const lockfileVersion = Number(lock?.lockfileVersion)
+    const extras = {lockfile, lockfileVersion: Number.isFinite(lockfileVersion) ? Math.trunc(lockfileVersion) : 0}
+    if (!lock?.packages || typeof lock.packages !== 'object' || Array.isArray(lock.packages)) {
+        return emptyGraph(STATE.PARTIAL, 'BUN_LOCK_PACKAGES_REQUIRED', extras)
+    }
+
+    const allKeys = Object.keys(lock.packages).sort(compareText)
+    const selectedKeys = allKeys.slice(0, MAX_PACKAGE_RECORDS)
+    const reasons = []
+    if (selectedKeys.length < allKeys.length) reasons.push('LOCKFILE_PACKAGE_RECORD_LIMIT_REACHED')
+
+    const records = new Map()
+    let invalidRecords = 0
+    for (const key of selectedKeys) {
+        const segments = bunKeySegments(key)
+        const record = segments ? bunPackageRecord(lock.packages[key]) : null
+        if (!record) {
+            invalidRecords++
+            continue
+        }
+        records.set(key, {...record, segments})
+    }
+    if (invalidRecords > 0) reasons.push('INVALID_LOCKFILE_PACKAGE_RECORDS')
+
+    // Node ids reuse packageId over the bun install-position key, so ids keep the
+    // exact "npm:name@version:hash12" shape the npm parser and sync sanitizer use,
+    // and node.name stays the bare package name that hosted BFS grounding matches.
+    const externalNodes = new Map()
+    let invalidPackageVersions = 0
+    for (const [key, record] of records) {
+        if (record.workspace) continue
+        const version = packageVersion(record.rawVersion)
+        if (!version) { invalidPackageVersions++; continue }
+        externalNodes.set(key, {
+            id: packageId(record.name, version, key),
+            name: record.name,
+            version,
+            direct: false,
+            dev: false,
+            optional: false,
+            peer: false,
+        })
+    }
+    if (invalidPackageVersions > 0) reasons.push('INVALID_LOCKFILE_PACKAGE_VERSIONS')
+
+    const workspaces = lock?.workspaces && typeof lock.workspaces === 'object' && !Array.isArray(lock.workspaces)
+        ? lock.workspaces
+        : null
+    if (!workspaces) reasons.push('BUN_LOCK_WORKSPACES_MISSING')
+
+    // Sources: every workspace member acts as '(root)' (matching how the npm parser
+    // treats workspace-local records), then every resolved external package.
+    const sources = []
+    for (const path of Object.keys(workspaces || {}).sort(compareText)) {
+        const meta = workspaces[path]
+        if (!meta || typeof meta !== 'object' || Array.isArray(meta)) continue
+        const workspaceName = path === '' ? null : safeToken(meta.name)
+        const segments = workspaceName && records.has(workspaceName) ? [workspaceName] : []
+        sources.push({sourceId: '(root)', segments, declarationRecord: bunDeclarationRecord(meta)})
+    }
+    for (const [key, record] of [...records].sort(([a], [b]) => compareText(a, b))) {
+        const node = externalNodes.get(key)
+        if (!node) continue
+        sources.push({sourceId: node.id, segments: record.segments, declarationRecord: bunDeclarationRecord(record.meta)})
+    }
+
+    const edgeMap = new Map()
+    const declarations = emptyDeclarations()
+    let declarationLimitReached = false
+    outer: for (const source of sources) {
+        for (const declaration of dependencyDeclarations(source.declarationRecord)) {
+            if (declarations.total >= MAX_DEPENDENCY_DECLARATIONS) {
+                declarationLimitReached = true
+                break outer
+            }
+            declarations.total++
+            const resolved = resolveBunDependency(source.segments, declaration.name, records)
+            if (resolved?.record.workspace) {
+                declarations.local++
+                continue
+            }
+            const node = resolved ? externalNodes.get(resolved.key) : null
+            if (!node) {
+                if (declaration.kind === 'optional' || declaration.kind === 'optional-peer') declarations.optionalMissing++
+                else declarations.unresolved++
+                continue
+            }
+            declarations.resolved++
+            if (source.sourceId === '(root)') node.direct = true
+            if (source.sourceId === node.id) continue
+            const edge = {from: source.sourceId, to: node.id, kind: declaration.kind}
+            edgeMap.set(`${edge.from}\0${edge.to}\0${edge.kind}`, edge)
+        }
+    }
+    if (declarationLimitReached) reasons.push('LOCKFILE_DEPENDENCY_DECLARATION_LIMIT_REACHED')
+    if (declarations.unresolved > 0) reasons.push('UNRESOLVED_LOCKFILE_DEPENDENCIES')
+
+    applyBunReachabilityFlags(externalNodes.values(), edgeMap.values())
+
+    return finalizeGraph({externalNodes, edgeMap, declarations, reasons, lockfile, lockfileVersion: extras.lockfileVersion})
+}
+
 export function buildPackageDependencyGraph(repoRoot) {
     const boundary = createRepoBoundary(repoRoot)
     if (!boundary.root) return emptyGraph(STATE.ERROR, 'INVALID_REPOSITORY_ROOT')
@@ -241,8 +494,9 @@ export function buildPackageDependencyGraph(repoRoot) {
         if (statSync(selected.path).size > MAX_LOCKFILE_BYTES) {
             return emptyGraph(STATE.ERROR, 'PACKAGE_LOCK_SIZE_LIMIT_REACHED', {lockfile: selected.lockfile})
         }
-        const lock = JSON.parse(readFileSync(selected.path, 'utf8'))
-        return parseLock(lock, selected.lockfile)
+        const raw = readFileSync(selected.path, 'utf8')
+        if (selected.lockfile === 'bun.lock') return parseBunLock(parseJsonc(raw), selected.lockfile)
+        return parseLock(JSON.parse(raw), selected.lockfile)
     } catch {
         return emptyGraph(STATE.ERROR, 'PACKAGE_LOCK_READ_ERROR', {lockfile: selected.lockfile})
     }

package/src/mcp/graph-context.mjs

@@ -133,7 +133,10 @@ export function ambiguityNote(query, info) {
 const bestByDegree = (g, list) =>
     list.reduce((best, n) => (degreeOf(g, n.id) > degreeOf(g, best.id) ? n : best), list[0])
 
-const QUERY_STOP = new Set('a an and are around architecture code do does explain find for from how in is me of or project repository show the through to trace what where which with'.split(' '))
+// Instructional words describe the requested answer, not repository concepts. Letting them become
+// fuzzy seeds made broad prompts select symbols such as `jest.config.cjs#path` for an HTTP request
+// path. Exact file/symbol questions still have seed_files / inspect_symbol as explicit controls.
+const QUERY_STOP = new Set('a an and are around architecture best code do does exact explain find focus focused for from how identify in inspect inspection is logic me of or path production project repository request requests rest show symbol symbols the through to trace what where which with'.split(' '))
 const QUERY_INTENTS = [
     ['bootstrap', ['bootstrap', 'startup', 'entrypoint', 'entry', 'main', 'root', 'app', 'application', 'applications', 'index', 'server', 'cli']],
     ['tool-execution', ['tool', 'tools', 'tooling', 'mcp', 'execution', 'execute', 'invocation', 'invoke', 'dispatch', 'dispatcher', 'handler', 'catalog', 'registry']],
@@ -275,6 +278,36 @@ function queryConcepts(query) {
     return concepts
 }
 
+// A code-shaped identifier in prose is stronger evidence than surrounding architecture words.
+// For example, `startMitigate` should seed its exact controller/service/messaging declarations,
+// not one arbitrary file for each of "controller", "service", and "flow". This remains bounded
+// label matching rather than semantic search; ambiguous identifiers are deliberately all retained.
+function exactIdentifierSeeds(g, query, limit, {repoRoot = null} = {}) {
+    const identifiers = [...new Set((String(query || '').match(/[A-Za-z_$][A-Za-z0-9_$]*/g) || [])
+        .filter((token) => /(?:[a-z0-9][A-Z]|_)/.test(token))
+        .map((token) => token.toLowerCase()))]
+    if (!identifiers.length) return []
+    const requestedClasses = requestedPathClasses(query)
+    const languageExtensions = requestedLanguages(query)
+    const classifier = createPathClassifier(repoRoot)
+    const classificationCache = new Map()
+    const matches = []
+    for (const identifier of identifiers) {
+        const candidates = g.nodes.filter((node) => {
+            const label = String(node.label || '').replace(/\(\)$/, '').toLowerCase()
+            return label === identifier
+                && matchesLanguage(node, languageExtensions)
+                && isQueryEligible(node, requestedClasses, classificationCache, classifier)
+        }).sort((left, right) => degreeOf(g, right.id) - degreeOf(g, left.id)
+            || String(left.id).localeCompare(String(right.id)))
+        for (const node of candidates) {
+            if (!matches.some((existing) => String(existing.id) === String(node.id))) matches.push(node)
+            if (matches.length >= limit) return matches
+        }
+    }
+    return matches
+}
+
 function conceptScore(g, node, concept, queryContext) {
     const id = normPath(node.id)
     const label = String(node.label ?? '').toLowerCase()
@@ -317,6 +350,8 @@ function conceptScore(g, node, concept, queryContext) {
 // Natural-language graph search keeps one strong candidate per concept before filling by aggregate
 // score. This prevents a broad architecture question from spending every seed on one dense API area.
 export function findSeeds(g, query, limit = 8, {repoRoot = null} = {}) {
+    const exact = exactIdentifierSeeds(g, query, limit, {repoRoot})
+    if (exact.length) return exact
     const concepts = queryConcepts(query)
     if (!concepts.length || limit <= 0) return []
     const requestedClasses = requestedPathClasses(query)

package/src/mcp/tools-actions.mjs

@@ -3,6 +3,7 @@
 // Hot-reloadable (re-imported by catalog.mjs on change).
 import {readFileSync, writeFileSync, existsSync, statSync, realpathSync} from 'node:fs'
 import {dirname, join, isAbsolute} from 'node:path'
+import {createHash} from 'node:crypto'
 import {prevGraphPathFor, diffGraphs, formatGraphDiff, graphStaleness} from './graph-context.mjs'
 import {buildGraphForRepo, defaultPrecisionMode} from '../build-graph.js'
 import {graphHomeDir, graphOutDirForModule, graphOutDirForRepo} from '../graph/layout.js'
@@ -13,8 +14,12 @@ import {createSyncPayload, createSyncPayloadV3, MAX_SYNC_BODY_BYTES} from './syn
 import {createEvidenceSnapshot} from './evidence-snapshot.mjs'
 import {writeCachedArchitectureContract} from '../analysis/architecture-contract.js'
 import {precisionSemanticInputsMatch, readPrecisionOverlay} from '../precision/lsp-overlay.js'
+import {toolResult} from './tool-result.mjs'
 
 const MAX_SYNC_GRAPH_FILE_BYTES = 64 * 1024 * 1024
+const SYNC_PREVIEW_TTL_MS = 5 * 60 * 1000
+const MAX_SYNC_PREVIEWS = 4
+const syncPreviews = new Map()
 
 function syncRepoLabel(repoRoot) {
     const basename = String(repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'repo'
@@ -22,6 +27,80 @@ function syncRepoLabel(repoRoot) {
     return (safe || 'repo').slice(0, 128)
 }
 
+function syncDestination(raw) {
+    let url
+    try { url = new URL(raw) } catch { throw new Error('WEAVATRIX_SYNC_URL is invalid') }
+    if (!['http:', 'https:'].includes(url.protocol)) throw new Error('WEAVATRIX_SYNC_URL must use HTTPS (or HTTP for loopback development)')
+    if (url.username || url.password) throw new Error('WEAVATRIX_SYNC_URL must not contain embedded credentials; use WEAVATRIX_SYNC_TOKEN')
+    if (url.hash) throw new Error('WEAVATRIX_SYNC_URL must not contain a fragment')
+    const loopback = ['localhost', '127.0.0.1', '[::1]', '::1'].includes(url.hostname.toLowerCase())
+    if (url.protocol !== 'https:' && !loopback) throw new Error('WEAVATRIX_SYNC_URL must use HTTPS unless the destination is loopback')
+    const display = `${url.origin}${url.pathname}${url.search ? ' (query redacted)' : ''}`
+    return {url: url.toString(), display}
+}
+
+function pruneSyncPreviews(now = Date.now()) {
+    for (const [token, preview] of syncPreviews) if (preview.expiresAt <= now) syncPreviews.delete(token)
+    while (syncPreviews.size >= MAX_SYNC_PREVIEWS) syncPreviews.delete(syncPreviews.keys().next().value)
+}
+
+function confirmationToken({url, repositoryId, payloadVersion, bodyHash}) {
+    return createHash('sha256')
+        .update(`weavatrix-sync-preview-v1\0${url}\0${repositoryId}\0${payloadVersion}\0${bodyHash}`)
+        .digest('hex').slice(0, 24)
+}
+
+function syncSectionSummary(payload) {
+    if (payload.syncPayloadV !== 3) return 'graph topology only (explicit V2 compatibility mode)'
+    const sections = payload.evidence?.sections || {}
+    const names = Object.entries(sections).map(([name, section]) => `${name}:${section?.state || section?.verdict || 'included'}`)
+    return names.join(', ') || 'bounded architecture/health/stack/package/duplicate evidence'
+}
+
+function syncPreviewText(preview, {expired = false} = {}) {
+    return [
+        `SYNC PREVIEW${expired ? ' (the supplied confirmation was missing, expired, or did not match)' : ''} — no network request was made.`,
+        `Destination: ${preview.destinationDisplay}.`,
+        `Repository: ${preview.repoName}; opaque repository UUID: ${preview.repositoryId}.`,
+        `Payload V${preview.payload.syncPayloadV}: ${preview.payload.nodes.length} nodes / ${preview.payload.links.length} edges, ${Math.round(preview.bodyBytes / 1024)} KB; body SHA-256 ${preview.bodyHash.slice(0, 12)}.`,
+        `Payload fields: ${Object.keys(preview.payload).sort().join(', ')}.`,
+        `Included sections: ${syncSectionSummary(preview.payload)}.`,
+        'Excluded by the wire allowlist: source bodies, snippets, absolute host paths, environment values, credentials, Git remotes, and unknown fields.',
+        `After the user approves this exact destination and summary, call sync_graph again within 5 minutes with dry_run:false and confirm_token: "${preview.token}".`,
+    ].join('\n')
+}
+
+async function sendSyncPreview(preview, timeoutMs) {
+    try {
+        const res = await fetch(preview.url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-weavatrix-payload-version': String(preview.payload.syncPayloadV),
+                'x-weavatrix-repo': preview.repoName,
+                'x-weavatrix-repository-id': preview.repositoryId,
+                ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
+            },
+            body: preview.body,
+            signal: AbortSignal.timeout(timeoutMs),
+        })
+        if (!res.ok) {
+            const accepted = res.headers?.get?.('x-weavatrix-accept-payload-versions')
+            const compatibility = (res.status === 415 || res.status === 422) && accepted
+                ? ` Endpoint accepts payload version(s) ${accepted}; create and approve a new V2 preview only if graph-only sync is intentional.`
+                : ''
+            return `Sync endpoint ${preview.destinationDisplay} answered HTTP ${res.status} — graph NOT accepted.${compatibility}`
+        }
+        syncPreviews.delete(preview.token)
+        const evidenceNote = preview.payload.syncPayloadV === 3
+            ? ` + evidence ${preview.payload.evidence?.snapshotHash?.slice(0, 12) || 'unknown'}`
+            : ''
+        return `Graph for ${preview.repoName} (${preview.payload.nodes.length} nodes / ${preview.payload.links.length} edges${evidenceNote}, ${Math.round(preview.bodyBytes / 1024)} KB) pushed to approved destination ${preview.destinationDisplay}.`
+    } catch (error) {
+        return `Sync failed: ${error.message} — the graph stays local; the approved preview remains retryable until it expires.`
+    }
+}
+
 export async function tRebuildGraph(g, args, ctx) {
     if (!ctx.repoRoot) return 'Rebuild needs the repo root (not provided to this server).'
     const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode)
@@ -188,8 +267,10 @@ export async function tPullArchitectureContract(g, args, ctx) {
     const token = process.env.WEAVATRIX_SYNC_TOKEN
     if (!syncUrl || !token) return 'Hosted architecture pull is not configured. Use the hosted profile with WEAVATRIX_SYNC_URL and WEAVATRIX_SYNC_TOKEN, or keep .weavatrix/architecture.json locally.'
     let url
-    try { url = process.env.WEAVATRIX_ARCHITECTURE_URL || new URL('/api/v1/architecture-contract', syncUrl).toString() }
-    catch { return 'WEAVATRIX_SYNC_URL is invalid.' }
+    try {
+        const configured = process.env.WEAVATRIX_ARCHITECTURE_URL || new URL('/api/v1/architecture-contract', syncUrl).toString()
+        url = syncDestination(configured).url
+    } catch (error) { return `Hosted architecture pull is not configured safely: ${error.message}.` }
     const registry = repositoryRecord(ctx.repoRoot, graphHomeDir())
         || registerRepository({repoPath: ctx.repoRoot, graphDir: graphOutDirForRepo(ctx.repoRoot), graphHome: graphHomeDir()})
     const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
@@ -199,8 +280,31 @@ export async function tPullArchitectureContract(g, args, ctx) {
             signal: AbortSignal.timeout(timeoutMs),
         })
         const body = await res.json().catch(() => null)
-        if (!res.ok) return `Hosted architecture endpoint answered HTTP ${res.status}; the local contract cache was not changed.`
-        if (body?.state === 'NOT_CONFIGURED' || !body?.contract) return 'Hosted target architecture is NOT_CONFIGURED. Define and save it in the Architecture editor first.'
+        if (!res.ok) {
+            const serverCode = String(body?.error?.code || body?.state || '').toUpperCase()
+            const state = res.status === 401 ? 'AUTH_REQUIRED'
+                : res.status === 403 ? 'FORBIDDEN'
+                    : res.status === 404 && ['REPOSITORY_NOT_FOUND', 'NOT_FOUND'].includes(serverCode) ? 'REPOSITORY_NOT_REGISTERED'
+                        : res.status === 404 ? 'ENDPOINT_NOT_FOUND'
+                        : res.status === 409 ? 'REPOSITORY_NOT_READY'
+                            : 'HTTP_ERROR'
+            const next = state === 'REPOSITORY_NOT_REGISTERED'
+                ? 'The Hosted endpoint is reachable, but this UUID has not completed a preview-confirmed repository sync.'
+                : state === 'ENDPOINT_NOT_FOUND'
+                    ? 'The configured architecture endpoint does not exist; verify WEAVATRIX_ARCHITECTURE_URL or the URL derived from WEAVATRIX_SYNC_URL.'
+                : res.status === 401 || res.status === 403
+                    ? 'Check the hosted token and repository access; no local cache entry was changed.'
+                    : res.status === 409
+                        ? 'Sync/register this repository first, then create or pull its target contract.'
+                        : 'Check the hosted service status and configured endpoint before retrying.'
+            return toolResult(`Hosted architecture pull: ${state} (HTTP ${res.status}). ${next} The previous local contract cache remains unchanged.`, {
+                state, httpStatus: res.status, serverCode: serverCode || null, cacheChanged: false,
+            })
+        }
+        if (body?.state === 'NOT_CONFIGURED' || !body?.contract) return toolResult(
+            'Hosted target architecture is NOT_CONFIGURED. Repository sync and authentication succeeded; define and save a target in the Architecture editor first.',
+            {state: 'NOT_CONFIGURED', repositoryId: registry.repositoryId, cacheChanged: false},
+        )
         const stored = writeCachedArchitectureContract(ctx.graphPath, body.contract)
         return `Pulled target architecture ${stored.contract.name} (${stored.contract.style}, ${stored.contract.enforcement}) into the local graph cache. get_architecture_contract and verify_architecture now use it.`
     } catch (error) {
@@ -208,14 +312,15 @@ export async function tPullArchitectureContract(g, args, ctx) {
     }
 }
 
-// Push the current graph.json to a user-configured endpoint. Off until WEAVATRIX_SYNC_URL is set.
-// The payload is graph metadata (paths, symbols/ranges, imports, edges, metrics), never file contents.
-export async function tSyncGraph(g, args, ctx) {
-    const url = process.env.WEAVATRIX_SYNC_URL
-    if (!url) {
+async function buildSyncPreview(g, args, ctx) {
+    const configuredUrl = process.env.WEAVATRIX_SYNC_URL
+    if (!configuredUrl) {
         return 'Graph sync is not configured (optional feature). Set WEAVATRIX_SYNC_URL to the upload endpoint'
             + ' (and WEAVATRIX_SYNC_TOKEN for bearer auth) in the MCP registration env, then call again.'
     }
+    let destination
+    try { destination = syncDestination(configuredUrl) }
+    catch (error) { return `Graph sync is not configured safely: ${error.message}.` }
     if (!g) return 'No graph loaded — build one first (open_repo / rebuild_graph).'
     let raw
     try {
@@ -249,32 +354,61 @@ export async function tSyncGraph(g, args, ctx) {
     const repoName = syncRepoLabel(ctx.repoRoot)
     const registry = repositoryRecord(ctx.repoRoot, graphHomeDir())
         || registerRepository({repoPath: ctx.repoRoot, graphDir: graphOutDirForRepo(ctx.repoRoot), graphHome: graphHomeDir()})
-    const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
-    try {
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                'x-weavatrix-payload-version': String(payload.syncPayloadV),
-                'x-weavatrix-repo': repoName,
-                'x-weavatrix-repository-id': registry.repositoryId,
-                ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
-            },
-            body,
-            signal: AbortSignal.timeout(timeoutMs),
-        })
-        if (!res.ok) {
-            const accepted = res.headers?.get?.('x-weavatrix-accept-payload-versions')
-            const compatibility = (res.status === 415 || res.status === 422) && accepted
-                ? ` Endpoint accepts payload version(s) ${accepted}; retry with payload_version:2 only if you intentionally want graph-only sync.`
-                : ''
-            return `Sync endpoint answered HTTP ${res.status} — graph NOT accepted.${compatibility}`
-        }
-        const evidenceNote = payload.syncPayloadV === 3
-            ? ` + evidence ${payload.evidence?.snapshotHash?.slice(0, 12) || 'unknown'}`
-            : ''
-        return `Graph for ${repoName} (${payload.nodes.length} nodes / ${payload.links.length} edges${evidenceNote}, ${Math.round(bodyBytes / 1024)} KB) pushed to ${url}.`
-    } catch (e) {
-        return `Sync failed: ${e.message} — the graph stays local.`
+    const bodyHash = createHash('sha256').update(body).digest('hex')
+    const token = confirmationToken({url: destination.url, repositoryId: registry.repositoryId, payloadVersion: payload.syncPayloadV, bodyHash})
+    const preview = {
+        token, url: destination.url, destinationDisplay: destination.display,
+        graphPath: ctx.graphPath, repoName, repositoryId: registry.repositoryId,
+        payload, body, bodyBytes, bodyHash, expiresAt: Date.now() + SYNC_PREVIEW_TTL_MS,
+    }
+    syncPreviews.set(token, preview)
+    return preview
+}
+
+function previewResult(preview, {expired = false} = {}) {
+    if (typeof preview === 'string') return preview
+    return toolResult(syncPreviewText(preview, {expired}), {
+        status: 'PREVIEW_READY', networkRequestMade: false,
+        destination: preview.destinationDisplay, repository: preview.repoName,
+        repositoryId: preview.repositoryId, payloadVersion: preview.payload.syncPayloadV,
+        nodes: preview.payload.nodes.length, links: preview.payload.links.length,
+        bodyBytes: preview.bodyBytes, bodyHash: preview.bodyHash,
+        payloadFields: Object.keys(preview.payload).sort(), sections: syncSectionSummary(preview.payload),
+        expiresAt: new Date(preview.expiresAt).toISOString(), confirmToken: preview.token,
+    }, {completeness: {status: 'COMPLETE', reason: 'exact allowlisted payload serialized locally; no network request made'}})
+}
+
+// Build the exact upload body and approval token without any network request. Kept separate from the
+// mutating tool so safety layers and humans can approve a local preview without authorizing egress.
+export async function tPreviewSyncGraph(g, args, ctx) {
+    pruneSyncPreviews()
+    return previewResult(await buildSyncPreview(g, args, ctx))
+}
+
+// Push the exact payload previously approved through preview_sync. The old dry_run form remains a
+// compatibility alias for one release, but can never send unless dry_run:false and the token matches.
+export async function tSyncGraph(g, args, ctx) {
+    if (args.dry_run !== false) {
+        pruneSyncPreviews()
+        const preview = await buildSyncPreview(g, args, ctx)
+        if (typeof preview === 'string') return preview
+        const suppliedToken = String(args.confirm_token || '').trim()
+        const exact = suppliedToken && suppliedToken === preview.token
+        return `${syncPreviewText(preview, {expired: !!suppliedToken && !exact})}${exact ? '\nConfirmation token recognized, but dry_run is still true; no network request was made.' : ''}`
+    }
+    const configuredUrl = process.env.WEAVATRIX_SYNC_URL
+    if (!configuredUrl) return 'Graph sync is not configured (optional feature). Set WEAVATRIX_SYNC_URL first.'
+    let destination
+    try { destination = syncDestination(configuredUrl) }
+    catch (error) { return `Graph sync is not configured safely: ${error.message}.` }
+    pruneSyncPreviews()
+    const suppliedToken = String(args.confirm_token || '').trim()
+    const approved = suppliedToken ? syncPreviews.get(suppliedToken) : null
+    if (approved && approved.expiresAt > Date.now()
+        && approved.url === destination.url && approved.graphPath === ctx.graphPath) {
+        const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
+        return sendSyncPreview(approved, timeoutMs)
     }
+    const preview = await buildSyncPreview(g, args, ctx)
+    return typeof preview === 'string' ? preview : syncPreviewText(preview, {expired: true})
 }