@zokizuan/satori-mcp 4.9.1 → 4.10.1

package/README.md

@@ -1,62 +1,64 @@
 # @zokizuan/satori-mcp
 
-MCP server for Satori — agent-safe semantic code search and indexing.
-
-## Features
-
-- Capability-driven execution via `CapabilityResolver`
-- Runtime-first `search_codebase` with explicit `scope`, `resultMode`, `groupBy`, and optional `debug` traces
-- Deterministic query-prefix operators in `search_codebase` (`lang:`, `path:`, `-path:`, `must:`, `exclude:`)
-- Default grouped-result diversity and auto changed-files ranking (`rankingMode="auto_changed_first"`)
-- First-class `call_graph` tool with deterministic node/edge sorting and capability-driven language support (currently TS/JS/Python)
-- Sidecar-backed `file_outline` tool for per-file symbol navigation and direct call_graph jump handles
-- Snapshot v3 safety with index fingerprints and strict `requires_reindex` access gates
-- Deterministic train-in-the-error responses for incompatible or legacy index states
-- Query-time exclusion support with `.gitignore`-style matching
-- Structured search telemetry logs (`[TELEMETRY]` JSON to `stderr`)
-- Zod-first tool schemas converted to MCP JSON Schema for `ListTools`
-- Auto-generated tool docs from live tool schemas
-- `read_file` line-range retrieval with default large-file truncation guard and optional `mode="annotated"` metadata envelope
-- Optional proactive sync watcher mode (debounced filesystem events for explicitly touched roots in the current session)
-- Index-time AST scope breadcrumbs (TS/JS/Python) rendered in search output as `🧬 Scope`
-- Fingerprint schema `dense_v3`/`hybrid_v3` with hard gate for all pre-v3 indexes
-
-## Architecture
+Read-only MCP server for Satori. It gives coding agents six deterministic tools for repo search, symbol navigation, call graph context, bounded file reads, and index lifecycle management.
 
+## Install
+
+Prefer the CLI installer when possible:
+
+```bash
+npx -y @zokizuan/satori-cli@0.3.2 install --client codex
+npx -y @zokizuan/satori-cli@0.3.2 install --client claude
+npx -y @zokizuan/satori-cli@0.3.2 doctor
 ```
-[MCP Client]
-    -> [index.ts bootstrap + ListTools/CallTool]
-    -> [tool registry]
-    -> [manage_index | search_codebase | call_graph | file_outline | read_file | list_codebases]
-    -> [ToolContext DI]
-       -> [CapabilityResolver]
-       -> [SnapshotManager v3 + access gate]
-       -> [Context / Vector store / Embedding / Reranker adapters]
+
+Manual MCP config:
+
+```json
+{
+  "mcpServers": {
+    "satori": {
+      "command": "npx",
+      "args": ["-y", "@zokizuan/satori-mcp@4.10.1"],
+      "timeout": 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"
+      }
+    }
+  }
+}
 ```
 
-Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposing call-chain traversal and file-level navigation as first-class operations.
+Keep startup timeout at `180000` for first-run package resolution.
+
+## Agent Workflow
 
-## read_file Behavior
+```text
+list_codebases
+manage_index action="create" path="/absolute/path/to/repo"
+search_codebase path="/absolute/path/to/repo" query="where is auth refresh handled"
+file_outline path="/absolute/path/to/repo" file="src/auth.ts"
+call_graph path="/absolute/path/to/repo" symbolRef={...} direction="both"
+read_file path="/absolute/path/to/repo/src/auth.ts" start_line=1 end_line=160
+```
+
+Important defaults:
 
-- Supports optional `start_line` and `end_line` (1-based, inclusive)
-- When no range is provided and file length exceeds `READ_FILE_MAX_LINES` (default `1000`), output is truncated and includes a continuation hint with `path` and next `start_line`
-- Optional `mode="annotated"` returns content plus `outlineStatus`, `outline`, `hasMore`, and reindex hints when sidecar data is unavailable
+- `search_codebase` starts with runtime code, grouped by symbol.
+- `search_codebase` runs freshness checks before returning results.
+- `read_file` is bounded and can return continuation hints.
+- `requires_reindex` means reindex first, then retry the original call.
+- `manage_index action="clear"` is destructive and should be explicit.
 
-## Proactive Sync
+## Runtime Requirements
 
-- Enabled by default. Set `MCP_ENABLE_WATCHER=false` to disable
-- Debounce window via `MCP_WATCH_DEBOUNCE_MS` (default `5000`)
-- Watchers are session-scoped: startup does not watch every indexed codebase, only roots touched by successful index/search/navigation/read flows in the current session
-- Watch events reuse the same incremental sync pipeline (`reindexByChange`)
-- Ignore control files (`.satoriignore`, root `.gitignore`) trigger no-reindex reconciliation:
-  - delete indexed paths now ignored by active rules
-  - incremental sync picks up newly unignored files
-  - signature checks in `ensureFreshness` keep this working even when watcher events are missed
-- Safety gates:
-  - Watch-triggered sync only runs for `indexed`/`sync_completed` codebases
-  - Events are dropped for `indexing`, `indexfailed`, and `requires_reindex`
-  - Ignored/hidden paths are excluded (`node_modules`, `.git`, build artifacts, dotfiles)
-- On shutdown (`SIGINT`/`SIGTERM`), watchers are explicitly closed
+Configure an embedding provider and Milvus-compatible backend before indexing. Supported embedding providers are OpenAI, VoyageAI, Gemini, and Ollama. Changing provider, model, dimension, vector store, or schema requires a reindex because those values are part of the index fingerprint.
 
 <!-- TOOLS_START -->
 
@@ -93,7 +95,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 |
 |---|---|---|---|---|
@@ -139,169 +141,21 @@ No parameters.
 
 <!-- TOOLS_END -->
 
-### `read_file.open_symbol` Fields
-
-`open_symbol` resolves symbols inside the same file passed in `read_file.path`.
-
-- `symbolId` (string, optional): deterministic symbol id to resolve in `path`.
-- `symbolLabel` (string, optional): exact symbol label to resolve in `path`.
-- `start_line` (integer, optional): direct 1-based start line for span-based jump.
-- `end_line` (integer, optional): direct 1-based end line (inclusive).
-
-## MCP Config Examples
-
-### JSON-style (Claude Desktop, Cursor)
-
-```json
-{
-  "mcpServers": {
-    "satori": {
-      "command": "npx",
-      "args": ["-y", "@zokizuan/satori-mcp@4.9.1"],
-      "timeout": 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"
-      }
-    }
-  }
-}
-```
-
-### TOML-style (Claude Code CLI)
-
-```toml
-[mcp_servers.satori]
-command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@4.9.1"]
-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" }
-```
+## Notes
 
-`MILVUS_TOKEN` is optional auth for endpoints that require it; local unauthenticated Milvus only needs `MILVUS_ADDRESS`.
+- `open_symbol` resolves exact symbols inside the same file passed to `read_file.path`.
+- `MILVUS_TOKEN` is optional auth; local unauthenticated Milvus only needs `MILVUS_ADDRESS`.
+- MCP startup does not require provider credentials or a live Milvus backend. Provider-backed calls report `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`.
 
-### Local development (when working on this repo)
-
-```json
-{
-  "mcpServers": {
-    "satori": {
-      "command": "node",
-      "args": ["/absolute/path/to/satori/packages/mcp/dist/index.js"],
-      "timeout": 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"
-      }
-    }
-  }
-}
-```
-
-Never commit real API keys/tokens into repo config files.
-
-## Run Locally
+## Local Development
 
 ```bash
 pnpm --filter @zokizuan/satori-mcp start
-```
-
-## Shell CLI (`@zokizuan/satori-cli`)
-
-The shell-first installer/client now lives in a separate package: `@zokizuan/satori-cli`.
-
-### Install / Uninstall
-
-Supported installer targets in Phase 1:
-- `codex`
-- `claude`
-- `all`
-
-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
-```
-
-Install and uninstall run before MCP session startup, only touch Satori-managed config, and copy/remove these packaged skills:
-- `satori-search`
-- `satori-navigation`
-- `satori-indexing`
-
-### Commands
-
-```bash
-satori-cli tools list
-satori-cli tool call <toolName> --args-json '{"path":"/abs/repo","query":"auth"}'
-satori-cli tool call <toolName> --args-file ./args.json
-satori-cli tool call <toolName> --args-json @-
-satori-cli <toolName> [schema-subset flags]
-```
-
-Global flags (`--startup-timeout-ms`, `--call-timeout-ms`, `--format`, `--debug`) must appear before the command token.
-Example: `satori-cli --debug tools list`.
-
-### Output + Exit Contract
-
-- `stdout`: JSON only
-- `stderr`: diagnostics and text summaries
-- exit `0`: success
-- exit `1`: tool-level error (`isError=true` or structured envelope `status!="ok"`)
-- exit `2`: usage/argument/schema-subset errors
-- exit `3`: startup/transport/protocol/timeout failures
-
-### Wrapper Flag Support
-
-Wrapper mode (`satori-cli <toolName> ...`) supports a strict subset from reflected `tools/list` schemas:
-
-- primitive properties (`string|number|integer|boolean`)
-- enums of primitives
-- arrays of primitives (repeat flags in insertion order)
-- object properties only via `--<prop>-json '{...}'`
-
-Tool-level flags that overlap global names are preserved in wrapper mode once command parsing starts.
-Example: `satori-cli search_codebase --path /repo --query auth --debug` forwards `debug=true` to the tool.
-For boolean wrapper flags, `--flag` implies `true` and `--flag false` is supported.
-
-Unsupported schema shapes (for example `oneOf`, `anyOf`, `$ref`, complex arrays, nested expansion) return `E_SCHEMA_UNSUPPORTED` with fallback guidance to `--args-json` / `--args-file`.
-
-### Run Mode Semantics
-
-When spawned by `satori-cli`, server process mode is `SATORI_RUN_MODE=cli`:
-
-- startup background loops are disabled (`verifyCloudState`, watcher mode, background sync)
-- stdio safety hardening is enabled (`stdout` protocol-only, logs to `stderr`)
-- tool behavior stays on-demand and uses the same six MCP tools
-
-`SATORI_CLI_STDOUT_GUARD=drop|redirect` controls accidental non-protocol stdout handling (`drop` default).
-
-### Startup vs Provider Setup
-
-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.
-
-## Development
-
-```bash
 pnpm --filter @zokizuan/satori-mcp build
 pnpm --filter @zokizuan/satori-mcp typecheck
 pnpm --filter @zokizuan/satori-mcp test
 pnpm --filter @zokizuan/satori-mcp docs:check
-pnpm --filter @zokizuan/satori-cli build
-pnpm --filter @zokizuan/satori-cli test
 ```
 
-`build` automatically runs docs generation from tool schemas.
+`build` regenerates the tool reference from live tool schemas.

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.1 [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.1
 
   # 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.1
 
   # 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.1
 
   # 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.1
         `);
 }
 //# 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.1",
   "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.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",