@zokizuan/satori-mcp 4.9.1 → 4.10.0

package/README.md

@@ -93,7 +93,7 @@ Unified semantic search with runtime-first defaults (start with scope="runtime")
 
 ### `call_graph`
 
-Traverse the prebuilt call graph sidecar for callers/callees/bidirectional symbol relationships (language support follows the core callGraphQuery capability set; currently TS/JS/Python).
+Traverse the prebuilt call graph sidecar for callers/callees/bidirectional symbol relationships (language support follows the core callGraphQuery capability set; currently TS/JS/Python). When present, testReferences are static call-graph references from test-like files to returned symbols; they are investigation hints and do not prove runtime coverage, assertion coverage, or that a test executed a path.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
@@ -157,7 +157,7 @@ No parameters.
   "mcpServers": {
     "satori": {
       "command": "npx",
-      "args": ["-y", "@zokizuan/satori-mcp@4.9.1"],
+      "args": ["-y", "@zokizuan/satori-mcp@4.10.0"],
       "timeout": 180000,
       "env": {
         "EMBEDDING_PROVIDER": "VoyageAI",
@@ -178,7 +178,7 @@ No parameters.
 ```toml
 [mcp_servers.satori]
 command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@4.9.1"]
+args = ["-y", "@zokizuan/satori-mcp@4.10.0"]
 startup_timeout_ms = 180000
 env = { EMBEDDING_PROVIDER = "VoyageAI", EMBEDDING_MODEL = "voyage-4-large", EMBEDDING_OUTPUT_DIMENSION = "1024", VOYAGEAI_API_KEY = "your-api-key", VOYAGEAI_RERANKER_MODEL = "rerank-2.5", MILVUS_ADDRESS = "your-milvus-endpoint", MILVUS_TOKEN = "your-milvus-token" }
 ```
@@ -230,11 +230,11 @@ Supported installer targets in Phase 1:
 Examples:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.3.0 install --client codex
-npx -y @zokizuan/satori-cli@0.3.0 install --client claude
-npx -y @zokizuan/satori-cli@0.3.0 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.3.0 uninstall --client codex
-npx -y @zokizuan/satori-cli@0.3.0 doctor
+npx -y @zokizuan/satori-cli@0.3.1 install --client codex
+npx -y @zokizuan/satori-cli@0.3.1 install --client claude
+npx -y @zokizuan/satori-cli@0.3.1 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.3.1 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.3.1 doctor
 ```
 
 Install and uninstall run before MCP session startup, only touch Satori-managed config, and copy/remove these packaged skills:
@@ -293,6 +293,8 @@ When spawned by `satori-cli`, server process mode is `SATORI_RUN_MODE=cli`:
 
 MCP startup does not require provider credentials, network access, or a live Milvus backend. The server should complete `initialize` and expose the six tools with an empty provider environment. Provider-backed calls (`manage_index create|reindex|sync|clear` and `search_codebase`) validate their required environment at call time and return `MISSING_PROVIDER_CONFIG` when setup is incomplete.
 
+`MISSING_PROVIDER_CONFIG` is an active setup failure only when it appears as a tool response `code` or `reason`. Seeing the string inside `search_codebase` results can simply mean the query matched Satori code that implements the setup error.
+
 ## Development
 
 ```bash

package/dist/config.js

@@ -169,7 +169,7 @@ export function showHelpMessage() {
     console.log(`
 Satori MCP Server
 
-Usage: npx -y @zokizuan/satori-mcp@4.9.1 [options]
+Usage: npx -y @zokizuan/satori-mcp@4.10.0 [options]
 
 Options:
   --help, -h                          Show this help message
@@ -206,16 +206,16 @@ Environment Variables:
 
 Examples:
   # Start MCP server with OpenAI and explicit Milvus address
-  OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.9.1
+  OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.10.0
 
   # Start MCP server with VoyageAI and specific model
-  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.9.1
+  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.10.0
 
   # Start MCP server with Gemini and specific model
-  EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.9.1
+  EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.10.0
 
   # Start MCP server with Ollama and specific model
-  EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.9.1
+  EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.10.0
         `);
 }
 //# sourceMappingURL=config.js.map

package/dist/core/call-graph.d.ts

@@ -29,6 +29,20 @@ export interface CallGraphEdge {
     };
     confidence: number;
 }
+export interface CallGraphTestReference {
+    file: string;
+    symbolId: string;
+    symbolLabel?: string;
+    span: CallGraphSpan;
+    site: {
+        file: string;
+        startLine: number;
+        endLine?: number;
+    };
+    targetSymbolId: string;
+    kind: CallGraphEdgeKind;
+    confidence: number;
+}
 export interface CallGraphNote {
     type: 'unresolved_edge' | 'dynamic_edge' | 'missing_symbol_metadata';
     file: string;
@@ -59,6 +73,7 @@ export interface CallGraphResponseSupported {
     edges: CallGraphEdge[];
     notes: CallGraphNote[];
     warnings?: string[];
+    testReferences?: CallGraphTestReference[];
     notesTruncated: boolean;
     totalNoteCount: number;
     returnedNoteCount: number;
@@ -95,6 +110,7 @@ export declare class CallGraphSidecarManager {
         depth: number;
         limit: number;
     }): CallGraphQueryResponse;
+    private buildTestReferences;
     private buildGraph;
     private buildSymbolIndex;
     private resolveTargetNode;
@@ -112,8 +128,12 @@ export declare class CallGraphSidecarManager {
     private getSidecarPath;
     private toRelativePath;
     private getEdgeKey;
+    private getTestReferenceKey;
+    private isTestPath;
+    private hasPathSegment;
     private sortNodes;
     private sortEdges;
+    private sortTestReferences;
     private sortNotes;
     private compareNullableNumbersAsc;
     private compareNullableStringsAsc;

package/dist/core/call-graph.js

@@ -9,6 +9,7 @@ const QUERY_SUPPORTED_EXTENSIONS = new Set(getSupportedExtensionsForCapability('
 const QUERY_SUPPORTED_LANGUAGE_IDS = getSupportedLanguageIdsForCapability('callGraphQuery');
 const DEFAULT_IGNORE_PATTERNS = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**', '**/coverage/**', '**/.next/**'];
 const DEFAULT_CALL_GRAPH_NOTE_LIMIT = 200;
+const DEFAULT_CALL_GRAPH_TEST_REFERENCE_LIMIT = 50;
 const CALL_KEYWORDS = new Set([
     'if', 'for', 'while', 'switch', 'catch', 'return', 'new', 'typeof', 'function', 'class', 'def', 'await', 'with', 'from', 'import',
 ]);
@@ -208,6 +209,7 @@ export class CallGraphSidecarManager {
         const notes = relevantNotes.slice(0, this.noteLimit);
         const notesTruncated = totalNoteCount > notes.length;
         const warnings = notesTruncated ? ['CALL_GRAPH_NOTES_TRUNCATED'] : undefined;
+        const testReferences = this.buildTestReferences(sidecar, nodeById, visited).slice(0, DEFAULT_CALL_GRAPH_TEST_REFERENCE_LIMIT);
         return {
             supported: true,
             direction: options.direction,
@@ -217,6 +219,7 @@ export class CallGraphSidecarManager {
             edges,
             notes,
             warnings,
+            ...(testReferences.length > 0 ? { testReferences } : {}),
             notesTruncated,
             totalNoteCount,
             returnedNoteCount: notes.length,
@@ -227,6 +230,37 @@ export class CallGraphSidecarManager {
             },
         };
     }
+    buildTestReferences(sidecar, nodeById, targetSymbolIds) {
+        const referencesByKey = new Map();
+        for (const edge of sidecar.edges) {
+            if (!targetSymbolIds.has(edge.dstSymbolId)) {
+                continue;
+            }
+            const source = nodeById.get(edge.srcSymbolId);
+            if (!source || !this.isTestPath(source.file)) {
+                continue;
+            }
+            const reference = {
+                file: source.file,
+                symbolId: source.symbolId,
+                symbolLabel: source.symbolLabel,
+                span: {
+                    startLine: source.span.startLine,
+                    endLine: source.span.endLine,
+                },
+                site: {
+                    file: edge.site.file,
+                    startLine: edge.site.startLine,
+                    ...(Number.isFinite(edge.site.endLine) ? { endLine: edge.site.endLine } : {}),
+                },
+                targetSymbolId: edge.dstSymbolId,
+                kind: edge.kind,
+                confidence: edge.confidence,
+            };
+            referencesByKey.set(this.getTestReferenceKey(reference), reference);
+        }
+        return this.sortTestReferences(Array.from(referencesByKey.values()));
+    }
     async buildGraph(codebaseRoot, files) {
         const nodeById = new Map();
         const fileCache = new Map();
@@ -569,6 +603,22 @@ export class CallGraphSidecarManager {
     getEdgeKey(edge) {
         return `${edge.srcSymbolId}:${edge.dstSymbolId}:${edge.kind}:${edge.site.file}:${edge.site.startLine}`;
     }
+    getTestReferenceKey(reference) {
+        return `${reference.symbolId}:${reference.targetSymbolId}:${reference.kind}:${reference.site.file}:${reference.site.startLine}`;
+    }
+    isTestPath(relativePath) {
+        const normalizedPath = relativePath.replace(/\\/g, '/').replace(/^\/+/, '').toLowerCase();
+        return this.hasPathSegment(normalizedPath, 'test')
+            || this.hasPathSegment(normalizedPath, 'tests')
+            || this.hasPathSegment(normalizedPath, '__tests__')
+            || /\.test\.[^/]+$/.test(normalizedPath)
+            || /\.spec\.[^/]+$/.test(normalizedPath);
+    }
+    hasPathSegment(normalizedPath, segment) {
+        return normalizedPath === segment
+            || normalizedPath.startsWith(`${segment}/`)
+            || normalizedPath.includes(`/${segment}/`);
+    }
     sortNodes(nodes) {
         return nodes.sort((a, b) => {
             const fileCmp = this.compareNullableStringsAsc(a.file, b.file);
@@ -597,6 +647,29 @@ export class CallGraphSidecarManager {
             return this.compareNullableNumbersAsc(a.site?.startLine, b.site?.startLine);
         });
     }
+    sortTestReferences(references) {
+        return references.sort((a, b) => {
+            const fileCmp = this.compareNullableStringsAsc(a.file, b.file);
+            if (fileCmp !== 0)
+                return fileCmp;
+            const startCmp = this.compareNullableNumbersAsc(a.span?.startLine, b.span?.startLine);
+            if (startCmp !== 0)
+                return startCmp;
+            const labelCmp = this.compareNullableStringsAsc(a.symbolLabel, b.symbolLabel);
+            if (labelCmp !== 0)
+                return labelCmp;
+            const symbolCmp = this.compareNullableStringsAsc(a.symbolId, b.symbolId);
+            if (symbolCmp !== 0)
+                return symbolCmp;
+            const targetCmp = this.compareNullableStringsAsc(a.targetSymbolId, b.targetSymbolId);
+            if (targetCmp !== 0)
+                return targetCmp;
+            const siteFileCmp = this.compareNullableStringsAsc(a.site?.file, b.site?.file);
+            if (siteFileCmp !== 0)
+                return siteFileCmp;
+            return this.compareNullableNumbersAsc(a.site?.startLine, b.site?.startLine);
+        });
+    }
     sortNotes(notes) {
         return notes.sort((a, b) => {
             const fileCmp = this.compareNullableStringsAsc(a.file, b.file);

package/dist/core/handlers.d.ts

@@ -111,6 +111,9 @@ export declare class ToolHandlers {
     private buildCallGraphHint;
     private sanitizeIndexedRelativeFilePath;
     private buildNavigationFallback;
+    private buildSearchNextActions;
+    private buildChangedCodeDebug;
+    private buildGeneratedArtifactsVerificationHint;
     private normalizeRelativeFilePath;
     private buildRequiresReindexFileOutlinePayload;
     private getOutlineStatusForLanguage;

package/dist/core/handlers.js

@@ -782,11 +782,12 @@ export class ToolHandlers {
             || normalizedPath.endsWith('.txt');
     }
     isGeneratedPath(normalizedPath) {
-        return normalizedPath.includes('/dist/')
-            || normalizedPath.includes('/build/')
-            || normalizedPath.includes('/coverage/')
-            || normalizedPath.includes('/.next/')
-            || normalizedPath.includes('/generated/')
+        return this.hasPathSegment(normalizedPath, 'dist')
+            || this.hasPathSegment(normalizedPath, 'build')
+            || this.hasPathSegment(normalizedPath, 'coverage')
+            || this.hasPathSegment(normalizedPath, '.next')
+            || this.hasPathSegment(normalizedPath, '.output')
+            || this.hasPathSegment(normalizedPath, 'generated')
             || normalizedPath.endsWith('.min.js')
             || normalizedPath.endsWith('.min.css');
     }
@@ -821,7 +822,8 @@ export class ToolHandlers {
         if (this.isGeneratedPath(normalized)
             || this.hasPathSegment(normalized, 'coverage')
             || this.hasPathSegment(normalized, 'dist')
-            || this.hasPathSegment(normalized, 'build'))
+            || this.hasPathSegment(normalized, 'build')
+            || this.hasPathSegment(normalized, '.output'))
             return 'generated';
         if (this.isTestPath(normalized))
             return 'tests';
@@ -1898,6 +1900,213 @@ export class ToolHandlers {
         }
         return fallback;
     }
+    buildSearchNextActions(codebaseRoot, relativeFilePath, span, callGraphHint, sidecarReadyForOutline) {
+        if (!callGraphHint.supported) {
+            return undefined;
+        }
+        const normalizedFile = this.sanitizeIndexedRelativeFilePath(relativeFilePath);
+        if (!normalizedFile) {
+            return undefined;
+        }
+        const safeStartLine = Number.isFinite(span.startLine) ? Math.max(1, Number(span.startLine)) : 1;
+        const safeEndLine = Number.isFinite(span.endLine) ? Math.max(safeStartLine, Number(span.endLine)) : safeStartLine;
+        const absolutePath = path.resolve(codebaseRoot, normalizedFile);
+        const symbolRef = {
+            ...callGraphHint.symbolRef,
+            file: normalizedFile,
+            span: {
+                startLine: safeStartLine,
+                endLine: safeEndLine,
+            }
+        };
+        const nextActions = {
+            openSymbol: {
+                tool: 'read_file',
+                args: {
+                    path: absolutePath,
+                    open_symbol: {
+                        symbolId: symbolRef.symbolId,
+                        ...(symbolRef.symbolLabel ? { symbolLabel: symbolRef.symbolLabel } : {}),
+                        start_line: safeStartLine,
+                        end_line: safeEndLine,
+                    }
+                }
+            },
+            traceCallers: {
+                tool: 'call_graph',
+                args: {
+                    path: codebaseRoot,
+                    symbolRef,
+                    direction: 'callers',
+                    depth: 1,
+                    limit: 20,
+                }
+            },
+            traceCallees: {
+                tool: 'call_graph',
+                args: {
+                    path: codebaseRoot,
+                    symbolRef,
+                    direction: 'callees',
+                    depth: 1,
+                    limit: 20,
+                }
+            }
+        };
+        if (sidecarReadyForOutline && this.getOutlineStatusForLanguage(normalizedFile) === 'ok') {
+            nextActions.outlineWindow = {
+                tool: 'file_outline',
+                args: {
+                    path: codebaseRoot,
+                    file: normalizedFile,
+                    start_line: safeStartLine,
+                    end_line: safeEndLine,
+                    resolveMode: 'outline',
+                }
+            };
+        }
+        return nextActions;
+    }
+    buildChangedCodeDebug(codebaseRoot, changedFilesState) {
+        if (!changedFilesState.available || changedFilesState.files.size === 0) {
+            return undefined;
+        }
+        const loadSidecar = this.callGraphManager?.loadSidecar;
+        if (typeof loadSidecar !== 'function') {
+            return undefined;
+        }
+        const sidecar = loadSidecar.call(this.callGraphManager, codebaseRoot);
+        if (!sidecar || !Array.isArray(sidecar.nodes) || !Array.isArray(sidecar.edges)) {
+            return undefined;
+        }
+        const changedFiles = Array.from(changedFilesState.files)
+            .map((file) => this.normalizeRelativeFilePath(file))
+            .filter((file) => file.length > 0 && !file.startsWith('..') && !path.posix.isAbsolute(file))
+            .sort((a, b) => a.localeCompare(b));
+        const changedFileSet = new Set(changedFiles);
+        const nodeById = new Map();
+        for (const node of sidecar.nodes) {
+            if (node && typeof node.symbolId === 'string') {
+                nodeById.set(node.symbolId, node);
+            }
+        }
+        const changedSymbols = sidecar.nodes
+            .filter((node) => node && typeof node.file === 'string' && changedFileSet.has(this.normalizeRelativeFilePath(node.file)))
+            .map((node) => ({
+            file: this.normalizeRelativeFilePath(node.file),
+            symbolId: String(node.symbolId),
+            ...(typeof node.symbolLabel === 'string' ? { symbolLabel: node.symbolLabel } : {}),
+            span: {
+                startLine: Number.isFinite(node.span?.startLine) ? Number(node.span.startLine) : 1,
+                endLine: Number.isFinite(node.span?.endLine) ? Number(node.span.endLine) : (Number.isFinite(node.span?.startLine) ? Number(node.span.startLine) : 1),
+            }
+        }))
+            .sort((a, b) => {
+            const fileCmp = this.compareNullableStringsAsc(a.file, b.file);
+            if (fileCmp !== 0)
+                return fileCmp;
+            const startCmp = this.compareNullableNumbersAsc(a.span?.startLine, b.span?.startLine);
+            if (startCmp !== 0)
+                return startCmp;
+            const labelCmp = this.compareNullableStringsAsc(a.symbolLabel, b.symbolLabel);
+            if (labelCmp !== 0)
+                return labelCmp;
+            return this.compareNullableStringsAsc(a.symbolId, b.symbolId);
+        });
+        const changedSymbolIds = new Set(changedSymbols.map((symbol) => symbol.symbolId));
+        const directCallers = sidecar.edges
+            .filter((edge) => edge && changedSymbolIds.has(edge.dstSymbolId))
+            .map((edge) => {
+            const caller = nodeById.get(edge.srcSymbolId);
+            if (!caller) {
+                return null;
+            }
+            const startLine = Number.isFinite(caller.span?.startLine) ? Number(caller.span.startLine) : 1;
+            const endLine = Number.isFinite(caller.span?.endLine) ? Number(caller.span.endLine) : startLine;
+            return {
+                targetSymbolId: String(edge.dstSymbolId),
+                file: this.normalizeRelativeFilePath(caller.file),
+                symbolId: String(caller.symbolId),
+                ...(typeof caller.symbolLabel === 'string' ? { symbolLabel: caller.symbolLabel } : {}),
+                span: {
+                    startLine,
+                    endLine,
+                },
+                site: {
+                    file: this.normalizeRelativeFilePath(edge.site?.file || caller.file),
+                    startLine: Number.isFinite(edge.site?.startLine) ? Number(edge.site.startLine) : startLine,
+                    ...(Number.isFinite(edge.site?.endLine) ? { endLine: Number(edge.site.endLine) } : {}),
+                },
+                kind: edge.kind === 'import' || edge.kind === 'dynamic' ? edge.kind : 'call',
+                confidence: Number.isFinite(edge.confidence) ? Number(edge.confidence) : 0,
+            };
+        })
+            .filter((caller) => Boolean(caller))
+            .sort((a, b) => {
+            const targetCmp = this.compareNullableStringsAsc(a.targetSymbolId, b.targetSymbolId);
+            if (targetCmp !== 0)
+                return targetCmp;
+            const fileCmp = this.compareNullableStringsAsc(a.file, b.file);
+            if (fileCmp !== 0)
+                return fileCmp;
+            const startCmp = this.compareNullableNumbersAsc(a.span?.startLine, b.span?.startLine);
+            if (startCmp !== 0)
+                return startCmp;
+            const labelCmp = this.compareNullableStringsAsc(a.symbolLabel, b.symbolLabel);
+            if (labelCmp !== 0)
+                return labelCmp;
+            const symbolCmp = this.compareNullableStringsAsc(a.symbolId, b.symbolId);
+            if (symbolCmp !== 0)
+                return symbolCmp;
+            return this.compareNullableNumbersAsc(a.site?.startLine, b.site?.startLine);
+        });
+        return {
+            files: changedFiles,
+            symbols: changedSymbols.slice(0, 50),
+            directCallers: directCallers.slice(0, 50),
+        };
+    }
+    buildGeneratedArtifactsVerificationHint(codebaseRoot, results) {
+        const byFile = new Map();
+        for (const result of results) {
+            const normalizedFile = this.sanitizeIndexedRelativeFilePath(result.file);
+            if (!normalizedFile) {
+                continue;
+            }
+            if (this.classifyNoiseCategory(normalizedFile) !== 'generated') {
+                continue;
+            }
+            const safeStartLine = Number.isFinite(result.span.startLine) ? Math.max(1, Number(result.span.startLine)) : 1;
+            const safeEndLine = Number.isFinite(result.span.endLine) ? Math.max(safeStartLine, Number(result.span.endLine)) : safeStartLine;
+            const existing = byFile.get(normalizedFile);
+            byFile.set(normalizedFile, existing
+                ? {
+                    startLine: Math.min(existing.startLine, safeStartLine),
+                    endLine: Math.max(existing.endLine, safeEndLine),
+                }
+                : { startLine: safeStartLine, endLine: safeEndLine });
+        }
+        const files = Array.from(byFile.keys()).sort((a, b) => a.localeCompare(b)).slice(0, 5);
+        if (files.length === 0) {
+            return undefined;
+        }
+        return {
+            reason: 'generated_outputs_present',
+            message: 'Generated or build output appeared in search context. Source matches do not prove generated output is current; verify the artifact directly when behavior depends on it.',
+            files,
+            nextSteps: files.map((file) => {
+                const span = byFile.get(file);
+                return {
+                    tool: 'read_file',
+                    args: {
+                        path: path.resolve(codebaseRoot, file),
+                        start_line: span.startLine,
+                        end_line: span.endLine,
+                    }
+                };
+            }),
+        };
+    }
     normalizeRelativeFilePath(relativeFilePath) {
         return relativeFilePath.replace(/\\/g, '/').replace(/^\.\/+/, '').trim();
     }
@@ -2976,6 +3185,9 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             const changedFilesState = input.rankingMode === 'auto_changed_first'
                 ? this.getChangedFilesForCodebase(effectiveRoot)
                 : { available: false, files: new Set() };
+            const debugChangedFilesState = input.debug
+                ? (input.rankingMode === 'auto_changed_first' ? changedFilesState : this.getChangedFilesForCodebase(effectiveRoot))
+                : undefined;
             const changedFilesCount = changedFilesState.files.size;
             const changedFilesBoostWithinThreshold = changedFilesCount > 0 && changedFilesCount <= SEARCH_CHANGED_FIRST_MAX_CHANGED_FILES;
             const changedFilesBoostEnabled = changedFilesState.available && changedFilesBoostWithinThreshold;
@@ -3260,6 +3472,9 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                         multiplier: SEARCH_CHANGED_FIRST_MULTIPLIER,
                         boostedCandidates,
                     },
+                    ...(debugChangedFilesState ? {
+                        changedCode: this.buildChangedCodeDebug(effectiveRoot, debugChangedFilesState),
+                    } : {}),
                     rerank: {
                         enabledByPolicy: rerankDecision.enabledByPolicy,
                         skippedByScopeDocs: rerankDecision.skippedByScopeDocs,
@@ -3313,13 +3528,22 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     } : {})
                 }));
                 const noiseMitigationHint = this.buildNoiseMitigationHint(effectiveRoot, rawResults.map((result) => result.file));
+                const generatedArtifactsHint = this.buildGeneratedArtifactsVerificationHint(effectiveRoot, rawResults.map((result) => ({
+                    file: result.file,
+                    span: result.span,
+                })));
                 const responseHints = {};
-                if (noiseMitigationHint || debugHintBase || proofDebugHint) {
+                if (noiseMitigationHint || debugHintBase || proofDebugHint || generatedArtifactsHint) {
                     responseHints.version = 1;
                 }
                 if (noiseMitigationHint) {
                     responseHints.noiseMitigation = noiseMitigationHint;
                 }
+                if (generatedArtifactsHint) {
+                    responseHints.verification = {
+                        generatedArtifacts: generatedArtifactsHint,
+                    };
+                }
                 if (debugHintBase) {
                     responseHints.debugSearch = debugHintBase;
                 }
@@ -3393,6 +3617,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                 const groupId = repSymbolId || this.buildFallbackGroupId(representative.result.relativePath, span);
                 const callGraphHint = this.buildCallGraphHint(representative.result.relativePath, span, representative.result.language || 'unknown', repSymbolId || undefined, repSymbolLabel || undefined);
                 const navigationFallback = this.buildNavigationFallback(effectiveRoot, representative.result.relativePath, span, callGraphHint, sidecarReadyForOutline);
+                const nextActions = this.buildSearchNextActions(effectiveRoot, representative.result.relativePath, span, callGraphHint, sidecarReadyForOutline);
                 groupedResults.push({
                     kind: "group",
                     groupId,
@@ -3407,6 +3632,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     collapsedChunkCount: group.chunks.length,
                     callGraphHint,
                     ...(navigationFallback ? { navigationFallback } : {}),
+                    ...(nextActions ? { nextActions } : {}),
                     preview: truncateContent(String(representative.result.content || ''), 4000),
                     __exactLexicalMatch: representative.exactLexicalMatch,
                     ...(input.debug ? {
@@ -3446,13 +3672,22 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             const diversityApplied = this.applyGroupDiversity(rankedGroupedResults, input.limit, input.groupBy);
             const visibleGroupedResults = diversityApplied.selected;
             const noiseMitigationHint = this.buildNoiseMitigationHint(effectiveRoot, visibleGroupedResults.map((result) => result.file));
+            const generatedArtifactsHint = this.buildGeneratedArtifactsVerificationHint(effectiveRoot, visibleGroupedResults.map((result) => ({
+                file: result.file,
+                span: result.span,
+            })));
             const responseHints = {};
-            if (noiseMitigationHint || debugHintBase || proofDebugHint) {
+            if (noiseMitigationHint || debugHintBase || proofDebugHint || generatedArtifactsHint) {
                 responseHints.version = 1;
             }
             if (noiseMitigationHint) {
                 responseHints.noiseMitigation = noiseMitigationHint;
             }
+            if (generatedArtifactsHint) {
+                responseHints.verification = {
+                    generatedArtifacts: generatedArtifactsHint,
+                };
+            }
             if (debugHintBase) {
                 responseHints.debugSearch = {
                     ...debugHintBase,

package/dist/core/search-types.d.ts

@@ -19,6 +19,44 @@ export type CallGraphHint = {
     supported: false;
     reason: "missing_symbol" | "unsupported_language";
 };
+export interface SearchNextActionReadSymbol {
+    tool: "read_file";
+    args: {
+        path: string;
+        open_symbol: {
+            symbolId: string;
+            symbolLabel?: string;
+            start_line: number;
+            end_line: number;
+        };
+    };
+}
+export interface SearchNextActionFileOutlineWindow {
+    tool: "file_outline";
+    args: {
+        path: string;
+        file: string;
+        start_line: number;
+        end_line: number;
+        resolveMode: "outline";
+    };
+}
+export interface SearchNextActionCallGraph {
+    tool: "call_graph";
+    args: {
+        path: string;
+        symbolRef: CallGraphSymbolRef;
+        direction: "callers" | "callees";
+        depth: number;
+        limit: number;
+    };
+}
+export interface SearchNextActions {
+    openSymbol?: SearchNextActionReadSymbol;
+    outlineWindow?: SearchNextActionFileOutlineWindow;
+    traceCallers?: SearchNextActionCallGraph;
+    traceCallees?: SearchNextActionCallGraph;
+}
 export interface SearchChunkResult {
     kind: "chunk";
     file: string;
@@ -57,6 +95,7 @@ export interface SearchGroupResult {
     collapsedChunkCount: number;
     callGraphHint: CallGraphHint;
     navigationFallback?: SearchNavigationFallback;
+    nextActions?: SearchNextActions;
     preview: string;
     debug?: {
         representativeChunkCount: number;
@@ -171,6 +210,29 @@ export interface SearchDebugHint {
         multiplier: number;
         boostedCandidates: number;
     };
+    changedCode?: {
+        files: string[];
+        symbols: Array<{
+            file: string;
+            symbolId: string;
+            symbolLabel?: string;
+            span: SearchSpan;
+        }>;
+        directCallers: Array<{
+            targetSymbolId: string;
+            file: string;
+            symbolId: string;
+            symbolLabel?: string;
+            span: SearchSpan;
+            site: {
+                file: string;
+                startLine: number;
+                endLine?: number;
+            };
+            kind: "call" | "import" | "dynamic";
+            confidence: number;
+        }>;
+    };
     rerank?: {
         enabledByPolicy: boolean;
         skippedByScopeDocs: boolean;
@@ -197,6 +259,14 @@ export interface SearchResponseHints extends Record<string, unknown> {
     version?: 1;
     noiseMitigation?: SearchNoiseMitigationHint;
     debugSearch?: SearchDebugHint;
+    verification?: {
+        generatedArtifacts?: {
+            reason: "generated_outputs_present";
+            message: string;
+            files: string[];
+            nextSteps: SearchNavigationFallbackReadSpan[];
+        };
+    };
 }
 export type NonOkReason = "indexing" | "requires_reindex" | "not_indexed" | "missing_provider_config";
 interface SearchBaseResponseEnvelope {

package/dist/tools/call_graph.js

@@ -18,7 +18,7 @@ const callGraphInputSchema = z.object({
 });
 export const callGraphTool = {
     name: 'call_graph',
-    description: () => 'Traverse the prebuilt call graph sidecar for callers/callees/bidirectional symbol relationships (language support follows the core callGraphQuery capability set; currently TS/JS/Python).',
+    description: () => 'Traverse the prebuilt call graph sidecar for callers/callees/bidirectional symbol relationships (language support follows the core callGraphQuery capability set; currently TS/JS/Python). When present, testReferences are static call-graph references from test-like files to returned symbols; they are investigation hints and do not prove runtime coverage, assertion coverage, or that a test executed a path.',
     inputSchemaZod: () => callGraphInputSchema,
     execute: async (args, ctx) => {
         const normalizedArgs = (args && typeof args === 'object')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-mcp",
-  "version": "4.9.1",
+  "version": "4.10.0",
   "description": "MCP server for Satori with agent-safe semantic search and indexing",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,7 @@
     "ignore": "^7.0.5",
     "zod": "^3.25.55",
     "zod-to-json-schema": "^3.25.1",
-    "@zokizuan/satori-core": "1.5.0"
+    "@zokizuan/satori-core": "1.5.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",