@zokizuan/satori-mcp 3.4.0 → 3.8.0

package/README.md

@@ -45,6 +45,10 @@ Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposi
 - Enabled by default. Set `MCP_ENABLE_WATCHER=false` to disable
 - Debounce window via `MCP_WATCH_DEBOUNCE_MS` (default `5000`)
 - 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`
@@ -57,7 +61,7 @@ Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposi
 
 ### `manage_index`
 
-Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path.
+Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path (no full reindex required). If you need immediate convergence after ignore edits, run action="sync" and then rerun search_codebase. Use action="reindex" for fingerprint/schema incompatibility or full rebuild recovery.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
@@ -71,7 +75,7 @@ Manage index lifecycle operations (create/reindex/sync/status/clear) for a codeb
 
 ### `search_codebase`
 
-Unified semantic search with runtime/docs scope control, grouped/raw output modes, deterministic ranking, and structured freshness decision.
+Unified semantic search with runtime/docs scope control, grouped/raw output modes, deterministic ranking, and structured freshness decisions. For runtime debugging, start with scope="runtime". If you need both runtime and docs context, use scope="mixed". If top results are dominated by tests/fixtures/docs, edit repo-root .satoriignore using your host/editor (examples, not exhaustive: **/*.test.*, **/*.spec.*, **/__tests__/**, **/__fixtures__/**, **/fixtures/**, coverage/**), wait one debounce window (MCP_WATCH_DEBOUNCE_MS, default 5000ms), then rerun search_codebase. For immediate convergence, run manage_index with {"action":"sync","path":"<same path used in search_codebase>"}.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
@@ -85,7 +89,7 @@ Unified semantic search with runtime/docs scope control, grouped/raw output mode
 
 ### `call_graph`
 
-Traverse the prebuilt TS/Python call graph sidecar for callers/callees/bidirectional symbol relationships.
+Traverse the prebuilt TS/JS/Python call graph sidecar for callers/callees/bidirectional symbol relationships.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
@@ -106,6 +110,9 @@ Return a sidecar-backed symbol outline for one file, including call_graph jump h
 | `start_line` | integer | no |  | Optional start line filter (1-based, inclusive). |
 | `end_line` | integer | no |  | Optional end line filter (1-based, inclusive). |
 | `limitSymbols` | integer | no | `500` | Maximum number of returned symbols after line filtering. |
+| `resolveMode` | enum("outline", "exact") | no | `"outline"` | Outline mode returns all symbols (windowed/limited). Exact mode resolves deterministic symbol matches in this file. |
+| `symbolIdExact` | string | no |  | Used with resolveMode="exact": exact symbolId match in the target file. |
+| `symbolLabelExact` | string | no |  | Used with resolveMode="exact": exact symbol label match in the target file. |
 
 ### `read_file`
 
@@ -117,6 +124,7 @@ Read file content from the local filesystem, with optional 1-based inclusive lin
 | `start_line` | integer | no |  | Optional start line (1-based, inclusive). |
 | `end_line` | integer | no |  | Optional end line (1-based, inclusive). |
 | `mode` | enum("plain", "annotated") | no | `"plain"` | Output mode. plain returns text only; annotated returns content plus sidecar-backed outline metadata. |
+| `open_symbol` | object | no |  | Optional deterministic symbol jump request for this file path. Uses exact symbol resolution within `path` when symbolId/symbolLabel is provided. |
 
 ### `list_codebases`
 
@@ -127,6 +135,15 @@ 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)

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 export type EmbeddingProvider = 'OpenAI' | 'VoyageAI' | 'Gemini' | 'Ollama';
 export type VectorStoreProvider = 'Milvus';
 export type FingerprintSource = 'verified' | 'assumed_v2';
+export declare const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 export interface IndexFingerprint {
     embeddingProvider: EmbeddingProvider;
     embeddingModel: string;
@@ -37,6 +38,10 @@ export interface CallGraphSidecarInfo {
     noteCount: number;
     fingerprint: IndexFingerprint;
 }
+export interface CodebaseIndexManifest {
+    indexedPaths: string[];
+    updatedAt: string;
+}
 export interface CodebaseSnapshotV1 {
     indexedCodebases: string[];
     indexingCodebases: string[] | Record<string, number>;
@@ -48,6 +53,9 @@ interface CodebaseInfoBase {
     fingerprintSource?: FingerprintSource;
     reindexReason?: 'legacy_unverified_fingerprint' | 'fingerprint_mismatch' | 'missing_fingerprint';
     callGraphSidecar?: CallGraphSidecarInfo;
+    indexManifest?: CodebaseIndexManifest;
+    ignoreRulesVersion?: number;
+    ignoreControlSignature?: string;
 }
 export interface CodebaseInfoIndexing extends CodebaseInfoBase {
     status: 'indexing';

package/dist/config.js

@@ -1,4 +1,5 @@
 import { envManager } from "@zokizuan/satori-core";
+export const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 // Helper function to get default model for each provider
 export function getDefaultModelForProvider(provider) {
     switch (provider) {
@@ -51,7 +52,6 @@ export function buildRuntimeIndexFingerprint(config, embeddingDimension) {
 export function createMcpConfig() {
     const defaultProvider = envManager.get('EMBEDDING_PROVIDER') || 'VoyageAI';
     const defaultReadFileMaxLines = 1000;
-    const defaultWatchDebounceMs = 5000;
     // Parse output dimension from env var
     const outputDimensionStr = envManager.get('EMBEDDING_OUTPUT_DIMENSION');
     let encoderOutputDimension;
@@ -92,7 +92,7 @@ export function createMcpConfig() {
     const watchSyncEnabled = watchSyncEnabledRaw
         ? watchSyncEnabledRaw.toLowerCase() === 'true'
         : true;
-    let watchDebounceMs = defaultWatchDebounceMs;
+    let watchDebounceMs = DEFAULT_WATCH_DEBOUNCE_MS;
     const watchDebounceRaw = envManager.get('MCP_WATCH_DEBOUNCE_MS');
     if (watchDebounceRaw) {
         const parsed = Number.parseInt(watchDebounceRaw, 10);
@@ -100,7 +100,7 @@ export function createMcpConfig() {
             watchDebounceMs = parsed;
         }
         else {
-            console.warn(`[WARN] Invalid MCP_WATCH_DEBOUNCE_MS value: ${watchDebounceRaw}. Using default ${defaultWatchDebounceMs}.`);
+            console.warn(`[WARN] Invalid MCP_WATCH_DEBOUNCE_MS value: ${watchDebounceRaw}. Using default ${DEFAULT_WATCH_DEBOUNCE_MS}.`);
         }
     }
     const config = {
@@ -140,7 +140,7 @@ export function logConfigurationSummary(config) {
     console.log(`[MCP]   Embedding Provider: ${config.encoderProvider}`);
     console.log(`[MCP]   Embedding Model: ${config.encoderModel}`);
     console.log(`[MCP]   Milvus Address: ${config.milvusEndpoint || (config.milvusApiToken ? '[Auto-resolve from token]' : '[Not configured]')}`);
-    console.log(`[MCP]   Proactive Watcher: ${config.watchSyncEnabled ? `enabled (${config.watchDebounceMs || 5000}ms debounce)` : 'disabled'}`);
+    console.log(`[MCP]   Proactive Watcher: ${config.watchSyncEnabled ? `enabled (${config.watchDebounceMs || DEFAULT_WATCH_DEBOUNCE_MS}ms debounce)` : 'disabled'}`);
     // Log provider-specific configuration without exposing sensitive data
     switch (config.encoderProvider) {
         case 'OpenAI':

package/dist/core/call-graph.js

@@ -3,9 +3,10 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import crypto from 'node:crypto';
 import ignore from 'ignore';
-import { AstCodeSplitter } from '@zokizuan/satori-core';
-const SUPPORTED_SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py']);
-const QUERY_SUPPORTED_EXTENSIONS = new Set(['.ts', '.tsx', '.py']);
+import { AstCodeSplitter, getLanguageIdFromExtension, getSupportedExtensionsForCapability, getSupportedLanguageIdsForCapability, } from '@zokizuan/satori-core';
+const SUPPORTED_SOURCE_EXTENSIONS = new Set(getSupportedExtensionsForCapability('callGraphBuild'));
+const QUERY_SUPPORTED_EXTENSIONS = new Set(getSupportedExtensionsForCapability('callGraphQuery'));
+const QUERY_SUPPORTED_LANGUAGE_IDS = getSupportedLanguageIdsForCapability('callGraphQuery');
 const DEFAULT_IGNORE_PATTERNS = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**', '**/coverage/**', '**/.next/**'];
 const CALL_KEYWORDS = new Set([
     'if', 'for', 'while', 'switch', 'catch', 'return', 'new', 'typeof', 'function', 'class', 'def', 'await', 'with', 'from', 'import',
@@ -478,11 +479,9 @@ export class CallGraphSidecarManager {
     }
     getSplitLanguage(relativePath) {
         const ext = path.extname(relativePath).toLowerCase();
-        if (ext === '.py') {
-            return 'python';
-        }
-        if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs') {
-            return ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs' ? 'javascript' : 'typescript';
+        const language = getLanguageIdFromExtension(ext, 'unknown');
+        if (language === 'python' || language === 'typescript' || language === 'javascript') {
+            return language;
         }
         return 'unknown';
     }
@@ -495,8 +494,9 @@ export class CallGraphSidecarManager {
             supported: false,
             reason: 'unsupported_language',
             hints: {
-                supportedExtensions: ['.ts', '.tsx', '.py'],
-                message: 'call_graph currently supports TypeScript and Python symbols.',
+                supportedExtensions: Array.from(QUERY_SUPPORTED_EXTENSIONS).sort((a, b) => a.localeCompare(b)),
+                supportedLanguages: QUERY_SUPPORTED_LANGUAGE_IDS,
+                message: 'call_graph currently supports TypeScript, JavaScript, and Python symbols.',
             },
         };
     }

package/dist/core/handlers.d.ts

@@ -34,8 +34,12 @@ export declare class ToolHandlers {
     private isTestPath;
     private isDocPath;
     private isGeneratedPath;
+    private isFixturePath;
     private isEntrypointPath;
     private classifyPathCategory;
+    private classifyNoiseCategory;
+    private roundRatio;
+    private buildNoiseMitigationHint;
     private shouldIncludeCategoryInScope;
     private parseIndexedAtMs;
     private getStalenessBucket;
@@ -64,6 +68,8 @@ export declare class ToolHandlers {
     private parseCodebaseFromMetadata;
     private resolveCollectionCodebasePath;
     private formatCollectionTimestamp;
+    private parseTimestampMs;
+    private resolveCollectionSortTimestampMs;
     private buildZillizCollectionLimitGuidance;
     private buildCollectionLimitMessage;
     private clearAllCollectionsForForceReindex;

package/dist/core/handlers.js

@@ -2,9 +2,10 @@ import * as fs from "fs";
 import * as path from "path";
 import crypto from "node:crypto";
 import ignore from "ignore";
-import { COLLECTION_LIMIT_MESSAGE } from "@zokizuan/satori-core";
+import { COLLECTION_LIMIT_MESSAGE, getSupportedExtensionsForCapability, isLanguageCapabilitySupportedForExtension, isLanguageCapabilitySupportedForLanguage, } from "@zokizuan/satori-core";
 import { ensureAbsolutePath, truncateContent, trackCodebasePath } from "../utils.js";
-import { SEARCH_MAX_CANDIDATES, SEARCH_PROXIMITY_WINDOW, SEARCH_RRF_K, SCOPE_PATH_MULTIPLIERS, STALENESS_THRESHOLDS_MS } from "./search-constants.js";
+import { DEFAULT_WATCH_DEBOUNCE_MS } from "../config.js";
+import { SEARCH_MAX_CANDIDATES, SEARCH_NOISE_HINT_PATTERNS, SEARCH_NOISE_HINT_THRESHOLD, SEARCH_NOISE_HINT_TOP_K, SEARCH_PROXIMITY_WINDOW, SEARCH_RRF_K, SCOPE_PATH_MULTIPLIERS, STALENESS_THRESHOLDS_MS } from "./search-constants.js";
 import { CallGraphSidecarManager } from "./call-graph.js";
 const COLLECTION_LIMIT_PATTERNS = [
     /exceeded the limit number of collections/i,
@@ -14,6 +15,8 @@ const COLLECTION_LIMIT_PATTERNS = [
 ];
 const SATORI_COLLECTION_PREFIXES = ['code_chunks_', 'hybrid_code_chunks_'];
 const ZILLIZ_FREE_TIER_COLLECTION_LIMIT = 5;
+const OUTLINE_SUPPORTED_EXTENSIONS = getSupportedExtensionsForCapability('fileOutline');
+const MIN_RELIABLE_COLLECTION_CREATED_AT_MS = Date.UTC(2000, 0, 1);
 function collectErrorFragments(value, output, visited, depth = 0) {
     if (value === null || value === undefined || depth > 4 || output.length >= 8) {
         return;
@@ -403,6 +406,10 @@ export class ToolHandlers {
             || normalizedPath.endsWith('.min.js')
             || normalizedPath.endsWith('.min.css');
     }
+    isFixturePath(normalizedPath) {
+        return this.hasPathSegment(normalizedPath, 'fixtures')
+            || this.hasPathSegment(normalizedPath, '__fixtures__');
+    }
     isEntrypointPath(normalizedPath) {
         const entryNames = ['main.', 'index.', 'app.', 'server.', 'cli.', 'entry.'];
         const baseName = normalizedPath.split('/').pop() || '';
@@ -424,6 +431,68 @@ export class ToolHandlers {
             return 'srcRuntime';
         return 'neutral';
     }
+    classifyNoiseCategory(relativePath) {
+        const normalized = this.normalizeSearchPath(relativePath);
+        // Deterministic precedence: generated > tests > fixtures > docs > runtime.
+        if (this.isGeneratedPath(normalized)
+            || this.hasPathSegment(normalized, 'coverage')
+            || this.hasPathSegment(normalized, 'dist')
+            || this.hasPathSegment(normalized, 'build'))
+            return 'generated';
+        if (this.isTestPath(normalized))
+            return 'tests';
+        if (this.isFixturePath(normalized))
+            return 'fixtures';
+        if (this.isDocPath(normalized))
+            return 'docs';
+        return 'runtime';
+    }
+    roundRatio(value) {
+        return Math.round(value * 100) / 100;
+    }
+    buildNoiseMitigationHint(filesInOrder) {
+        if (!Array.isArray(filesInOrder) || filesInOrder.length === 0) {
+            return undefined;
+        }
+        const topK = Math.min(SEARCH_NOISE_HINT_TOP_K, filesInOrder.length);
+        if (topK <= 0) {
+            return undefined;
+        }
+        const counts = {
+            tests: 0,
+            fixtures: 0,
+            docs: 0,
+            generated: 0,
+            runtime: 0,
+        };
+        for (let i = 0; i < topK; i++) {
+            const category = this.classifyNoiseCategory(filesInOrder[i]);
+            counts[category] += 1;
+        }
+        const noisyRatio = (counts.tests + counts.fixtures + counts.docs + counts.generated) / topK;
+        if (noisyRatio < SEARCH_NOISE_HINT_THRESHOLD) {
+            return undefined;
+        }
+        const ratios = {
+            tests: this.roundRatio(counts.tests / topK),
+            fixtures: this.roundRatio(counts.fixtures / topK),
+            docs: this.roundRatio(counts.docs / topK),
+            generated: this.roundRatio(counts.generated / topK),
+            runtime: this.roundRatio(counts.runtime / topK),
+        };
+        const debounceMs = typeof this.syncManager?.getWatchDebounceMs === 'function'
+            ? this.syncManager.getWatchDebounceMs()
+            : DEFAULT_WATCH_DEBOUNCE_MS;
+        return {
+            reason: 'top_results_noise_dominant',
+            topK,
+            ratios,
+            recommendedScope: 'runtime',
+            suggestedIgnorePatterns: [...SEARCH_NOISE_HINT_PATTERNS],
+            debounceMs,
+            nextStep: 'Use scope="runtime". If you still need docs context, use scope="mixed". Edit repo-root .satoriignore using your host/editor, wait one debounce window, rerun search_codebase, or run manage_index with {"action":"sync","path":"<same path used in search_codebase>"} for immediate convergence.',
+        };
+    }
     shouldIncludeCategoryInScope(scope, category) {
         if (scope === 'runtime') {
             return category !== 'docs' && category !== 'tests';
@@ -473,13 +542,12 @@ export class ToolHandlers {
         return `grp_${digest}`;
     }
     isCallGraphLanguageSupported(language, file) {
-        const normalized = String(language || '').toLowerCase();
-        if (normalized === 'typescript' || normalized === 'ts' || normalized === 'python' || normalized === 'py') {
+        if (isLanguageCapabilitySupportedForLanguage(language, 'callGraphQuery')) {
             return true;
         }
         if (typeof file === 'string') {
             const ext = path.extname(file).toLowerCase();
-            return ext === '.ts' || ext === '.tsx' || ext === '.py';
+            return isLanguageCapabilitySupportedForExtension(ext, 'callGraphQuery');
         }
         return false;
     }
@@ -574,9 +642,9 @@ export class ToolHandlers {
         }
         return 'not_ready';
     }
-    getContextIgnorePatterns() {
+    getContextIgnorePatterns(codebasePath) {
         if (typeof this.context.getActiveIgnorePatterns === 'function') {
-            const patterns = this.context.getActiveIgnorePatterns();
+            const patterns = this.context.getActiveIgnorePatterns(codebasePath);
             if (Array.isArray(patterns)) {
                 return patterns.filter((pattern) => typeof pattern === 'string');
             }
@@ -585,7 +653,7 @@ export class ToolHandlers {
     }
     async rebuildCallGraphForIndex(codebasePath) {
         try {
-            const sidecar = await this.callGraphManager.rebuildForCodebase(codebasePath, this.getContextIgnorePatterns());
+            const sidecar = await this.callGraphManager.rebuildForCodebase(codebasePath, this.getContextIgnorePatterns(codebasePath));
             this.snapshotManager.setCodebaseCallGraphSidecar(codebasePath, sidecar);
             this.snapshotManager.saveCodebaseSnapshot();
             console.log(`[CALL-GRAPH] Rebuilt sidecar for '${codebasePath}' (${sidecar.nodeCount} nodes, ${sidecar.edgeCount} edges).`);
@@ -596,7 +664,7 @@ export class ToolHandlers {
     }
     async rebuildCallGraphForSyncDelta(codebasePath, changedFiles) {
         try {
-            const sidecar = await this.callGraphManager.rebuildIfSupportedDelta(codebasePath, changedFiles, this.getContextIgnorePatterns());
+            const sidecar = await this.callGraphManager.rebuildIfSupportedDelta(codebasePath, changedFiles, this.getContextIgnorePatterns(codebasePath));
             if (!sidecar) {
                 return false;
             }
@@ -707,6 +775,27 @@ export class ToolHandlers {
         }
         return new Date(timestamp).toISOString();
     }
+    parseTimestampMs(timestamp) {
+        if (!timestamp) {
+            return undefined;
+        }
+        const parsed = Date.parse(timestamp);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    resolveCollectionSortTimestampMs(createdAt, codebasePath, snapshotLastUpdatedByPath) {
+        const createdAtMs = this.parseTimestampMs(createdAt);
+        const snapshotMs = codebasePath ? snapshotLastUpdatedByPath.get(codebasePath) : undefined;
+        // Prefer collection metadata when it looks reliable.
+        if (createdAtMs !== undefined && createdAtMs >= MIN_RELIABLE_COLLECTION_CREATED_AT_MS) {
+            return createdAtMs;
+        }
+        // Fallback to snapshot timestamps when collection metadata is missing or suspicious.
+        if (snapshotMs !== undefined) {
+            return snapshotMs;
+        }
+        // Last resort for deterministic ordering when nothing else is available.
+        return createdAtMs;
+    }
     async buildZillizCollectionLimitGuidance(targetCodebasePath) {
         const targetCollectionName = this.context.resolveCollectionName(targetCodebasePath);
         const vectorDb = this.getVectorStore();
@@ -717,6 +806,13 @@ export class ToolHandlers {
         for (const codebasePath of trackedCodebases) {
             byCollectionName.set(this.context.resolveCollectionName(codebasePath), codebasePath);
         }
+        const snapshotLastUpdatedByPath = new Map();
+        for (const entry of this.snapshotManager.getAllCodebases()) {
+            const lastUpdatedMs = this.parseTimestampMs(entry.info.lastUpdated);
+            if (lastUpdatedMs !== undefined) {
+                snapshotLastUpdatedByPath.set(entry.path, lastUpdatedMs);
+            }
+        }
         const candidates = [];
         for (const detail of codeCollections) {
             const codebasePath = await this.resolveCollectionCodebasePath(vectorDb, detail.name, byCollectionName);
@@ -725,15 +821,14 @@ export class ToolHandlers {
                 createdAt: detail.createdAt,
                 codebasePath,
                 isTargetCollection: detail.name === targetCollectionName,
+                sortTimestampMs: this.resolveCollectionSortTimestampMs(detail.createdAt, codebasePath, snapshotLastUpdatedByPath),
             });
         }
         candidates.sort((a, b) => {
-            const aTime = a.createdAt ? Date.parse(a.createdAt) : NaN;
-            const bTime = b.createdAt ? Date.parse(b.createdAt) : NaN;
-            const aValid = Number.isFinite(aTime);
-            const bValid = Number.isFinite(bTime);
+            const aValid = Number.isFinite(a.sortTimestampMs);
+            const bValid = Number.isFinite(b.sortTimestampMs);
             if (aValid && bValid) {
-                return aTime - bTime;
+                return a.sortTimestampMs - b.sortTimestampMs;
             }
             if (aValid)
                 return -1;
@@ -1237,7 +1332,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             await this.context.loadResolvedIgnorePatterns(absolutePath);
             // Initialize file synchronizer with proper ignore patterns (including project-specific patterns)
             const { FileSynchronizer } = await import("@zokizuan/satori-core");
-            const ignorePatterns = this.context.getActiveIgnorePatterns() || [];
+            const ignorePatterns = this.context.getActiveIgnorePatterns(absolutePath) || [];
             console.log(`[BACKGROUND-INDEX] Using ignore patterns: ${ignorePatterns.join(', ')}`);
             const synchronizer = new FileSynchronizer(absolutePath, ignorePatterns);
             await synchronizer.initialize();
@@ -1269,6 +1364,12 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             console.log(`[BACKGROUND-INDEX] ✅ Indexing completed successfully! Files: ${stats.indexedFiles}, Chunks: ${stats.totalChunks}`);
             // Set codebase to indexed status with complete statistics
             this.snapshotManager.setCodebaseIndexed(absolutePath, stats, this.runtimeFingerprint, 'verified');
+            if (typeof this.context.getTrackedRelativePaths === 'function') {
+                const trackedPaths = this.context.getTrackedRelativePaths(absolutePath);
+                if (typeof this.snapshotManager.setCodebaseIndexManifest === 'function') {
+                    this.snapshotManager.setCodebaseIndexManifest(absolutePath, trackedPaths);
+                }
+            }
             this.indexingStats = { indexedFiles: stats.indexedFiles, totalChunks: stats.totalChunks };
             // Save snapshot after updating codebase lists
             this.snapshotManager.saveCodebaseSnapshot();
@@ -1568,6 +1669,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                         }
                     } : {})
                 }));
+                const noiseMitigationHint = this.buildNoiseMitigationHint(rawResults.map((result) => result.file));
                 const envelope = {
                     status: "ok",
                     path: absolutePath,
@@ -1578,6 +1680,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     resultMode: "raw",
                     freshnessDecision,
                     ...(searchWarnings.length > 0 ? { warnings: searchWarnings } : {}),
+                    ...(noiseMitigationHint ? { hints: { version: 1, noiseMitigation: noiseMitigationHint } } : {}),
                     results: rawResults
                 };
                 return {
@@ -1666,6 +1769,8 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     return labelCmp;
                 return this.compareNullableStringsAsc(a.symbolId, b.symbolId);
             });
+            const visibleGroupedResults = groupedResults.slice(0, input.limit);
+            const noiseMitigationHint = this.buildNoiseMitigationHint(visibleGroupedResults.map((result) => result.file));
             const envelope = {
                 status: "ok",
                 path: absolutePath,
@@ -1676,7 +1781,8 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                 resultMode: "grouped",
                 freshnessDecision,
                 ...(searchWarnings.length > 0 ? { warnings: searchWarnings } : {}),
-                results: groupedResults.slice(0, input.limit)
+                ...(noiseMitigationHint ? { hints: { version: 1, noiseMitigation: noiseMitigationHint } } : {}),
+                results: visibleGroupedResults
             };
             return {
                 content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
@@ -1705,6 +1811,9 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             : 500;
         const requestedStartLine = Number.isFinite(args?.start_line) ? Math.max(1, Number(args.start_line)) : undefined;
         const requestedEndLine = Number.isFinite(args?.end_line) ? Math.max(1, Number(args.end_line)) : undefined;
+        const resolveMode = args?.resolveMode === 'exact' ? 'exact' : 'outline';
+        const symbolIdExact = typeof args?.symbolIdExact === 'string' ? args.symbolIdExact.trim() : undefined;
+        const symbolLabelExact = typeof args?.symbolLabelExact === 'string' ? args.symbolLabelExact.trim() : undefined;
         try {
             await this.syncIndexedCodebasesFromCloud();
             const absoluteRoot = ensureAbsolutePath(args.path);
@@ -1805,7 +1914,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     file: normalizedFile,
                     outline: null,
                     hasMore: false,
-                    message: `File '${normalizedFile}' is not supported for sidecar outline. Supported extensions: .ts, .tsx, .py.`
+                    message: `File '${normalizedFile}' is not supported for sidecar outline. Supported extensions: ${OUTLINE_SUPPORTED_EXTENSIONS.join(', ')}.`
                 };
                 return {
                     content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
@@ -1859,13 +1968,55 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     }
                 };
             }));
-            const hasMore = symbols.length > limitSymbols;
             const missingSymbolMetadataCount = sidecar.notes.filter((note) => {
                 return note.type === 'missing_symbol_metadata' && this.normalizeRelativeFilePath(note.file) === normalizedFile;
             }).length;
             const warnings = missingSymbolMetadataCount > 0
                 ? [`OUTLINE_MISSING_SYMBOL_METADATA:${missingSymbolMetadataCount}`]
                 : undefined;
+            if (resolveMode === 'exact') {
+                const exactMatches = this.sortFileOutlineSymbols(symbols.filter((symbol) => {
+                    if (symbolIdExact && symbol.symbolId !== symbolIdExact) {
+                        return false;
+                    }
+                    if (symbolLabelExact && symbol.symbolLabel !== symbolLabelExact) {
+                        return false;
+                    }
+                    return true;
+                }));
+                if (exactMatches.length === 0) {
+                    const payload = {
+                        status: 'not_found',
+                        path: absoluteRoot,
+                        file: normalizedFile,
+                        outline: null,
+                        hasMore: false,
+                        message: 'No exact symbol match found in file outline.',
+                        ...(warnings ? { warnings } : {})
+                    };
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+                    };
+                }
+                const hasMoreExact = exactMatches.length > limitSymbols;
+                const exactPayload = {
+                    status: exactMatches.length > 1 ? 'ambiguous' : 'ok',
+                    path: absoluteRoot,
+                    file: normalizedFile,
+                    outline: {
+                        symbols: exactMatches.slice(0, limitSymbols)
+                    },
+                    hasMore: hasMoreExact,
+                    ...(exactMatches.length > 1 ? {
+                        message: `Multiple exact symbol matches found (${exactMatches.length}). Narrow with symbolIdExact for deterministic selection.`
+                    } : {}),
+                    ...(warnings ? { warnings } : {})
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(exactPayload, null, 2) }]
+                };
+            }
+            const hasMore = symbols.length > limitSymbols;
             const payload = {
                 status: 'ok',
                 path: absoluteRoot,
@@ -2329,6 +2480,12 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                 removed: syncStats.removed,
                 modified: syncStats.modified
             };
+            if (typeof this.context.getTrackedRelativePaths === 'function') {
+                const trackedPaths = this.context.getTrackedRelativePaths(absolutePath);
+                if (typeof this.snapshotManager.setCodebaseIndexManifest === 'function') {
+                    this.snapshotManager.setCodebaseIndexManifest(absolutePath, trackedPaths);
+                }
+            }
             // Store sync result in snapshot
             this.snapshotManager.setCodebaseSyncCompleted(absolutePath, syncTotals, this.runtimeFingerprint, 'verified');
             this.snapshotManager.saveCodebaseSnapshot();

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

@@ -1,6 +1,9 @@
 export declare const SEARCH_RRF_K = 60;
 export declare const SEARCH_MAX_CANDIDATES = 80;
 export declare const SEARCH_PROXIMITY_WINDOW = 25;
+export declare const SEARCH_NOISE_HINT_TOP_K = 5;
+export declare const SEARCH_NOISE_HINT_THRESHOLD = 0.6;
+export declare const SEARCH_NOISE_HINT_PATTERNS: readonly ["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/__fixtures__/**", "**/fixtures/**", "coverage/**"];
 export declare const STALENESS_THRESHOLDS_MS: {
     readonly fresh: number;
     readonly aging: number;
@@ -8,6 +11,7 @@ export declare const STALENESS_THRESHOLDS_MS: {
 export type SearchScope = 'runtime' | 'mixed' | 'docs';
 export type SearchResultMode = 'grouped' | 'raw';
 export type SearchGroupBy = 'symbol' | 'file';
+export type SearchNoiseCategory = 'tests' | 'fixtures' | 'docs' | 'generated' | 'runtime';
 export type PathCategory = 'entrypoint' | 'core' | 'srcRuntime' | 'neutral' | 'tests' | 'docs' | 'generated';
 export declare const SCOPE_PATH_MULTIPLIERS: Record<SearchScope, Record<PathCategory, number>>;
 //# sourceMappingURL=search-constants.d.ts.map

package/dist/core/search-constants.js

@@ -1,6 +1,16 @@
 export const SEARCH_RRF_K = 60;
 export const SEARCH_MAX_CANDIDATES = 80;
 export const SEARCH_PROXIMITY_WINDOW = 25;
+export const SEARCH_NOISE_HINT_TOP_K = 5;
+export const SEARCH_NOISE_HINT_THRESHOLD = 0.60;
+export const SEARCH_NOISE_HINT_PATTERNS = [
+    '**/*.test.*',
+    '**/*.spec.*',
+    '**/__tests__/**',
+    '**/__fixtures__/**',
+    '**/fixtures/**',
+    'coverage/**',
+];
 export const STALENESS_THRESHOLDS_MS = {
     fresh: 30 * 60 * 1000,
     aging: 24 * 60 * 60 * 1000,

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

@@ -1,5 +1,5 @@
 import { FreshnessDecision } from "./sync.js";
-import { SearchGroupBy, SearchResultMode, SearchScope } from "./search-constants.js";
+import { SearchGroupBy, SearchNoiseCategory, SearchResultMode, SearchScope } from "./search-constants.js";
 import { FingerprintSource, IndexFingerprint } from "../config.js";
 export type StalenessBucket = "fresh" | "aging" | "stale" | "unknown";
 export interface SearchSpan {
@@ -65,6 +65,19 @@ export interface FingerprintCompatibilityDiagnostics {
     reindexReason?: "legacy_unverified_fingerprint" | "fingerprint_mismatch" | "missing_fingerprint";
     statusAtCheck?: "indexed" | "indexing" | "indexfailed" | "sync_completed" | "requires_reindex" | "not_found";
 }
+export interface SearchNoiseMitigationHint {
+    reason: "top_results_noise_dominant";
+    topK: number;
+    ratios: Record<SearchNoiseCategory, number>;
+    recommendedScope: "runtime";
+    suggestedIgnorePatterns: string[];
+    debounceMs: number;
+    nextStep: string;
+}
+export interface SearchResponseHints extends Record<string, unknown> {
+    version?: 1;
+    noiseMitigation?: SearchNoiseMitigationHint;
+}
 interface SearchBaseResponseEnvelope {
     status: "ok" | "requires_reindex" | "not_indexed";
     path: string;
@@ -77,7 +90,7 @@ interface SearchBaseResponseEnvelope {
     } | null;
     warnings?: string[];
     message?: string;
-    hints?: Record<string, unknown>;
+    hints?: SearchResponseHints;
     compatibility?: FingerprintCompatibilityDiagnostics;
 }
 export interface SearchGroupedResponseEnvelope extends SearchBaseResponseEnvelope {
@@ -104,8 +117,11 @@ export interface FileOutlineInput {
     start_line?: number;
     end_line?: number;
     limitSymbols?: number;
+    resolveMode?: "outline" | "exact";
+    symbolIdExact?: string;
+    symbolLabelExact?: string;
 }
-export type FileOutlineStatus = "ok" | "not_found" | "requires_reindex" | "unsupported";
+export type FileOutlineStatus = "ok" | "not_found" | "requires_reindex" | "unsupported" | "ambiguous";
 export interface FileOutlineSymbolResult {
     symbolId: string;
     symbolLabel: string;

package/dist/core/snapshot.d.ts

@@ -49,6 +49,11 @@ export declare class SnapshotManager {
     }, indexFingerprint?: IndexFingerprint, fingerprintSource?: FingerprintSource): void;
     setCodebaseRequiresReindex(codebasePath: string, reason: 'legacy_unverified_fingerprint' | 'fingerprint_mismatch' | 'missing_fingerprint', message?: string): void;
     setCodebaseCallGraphSidecar(codebasePath: string, sidecar: CallGraphSidecarInfo): void;
+    setCodebaseIndexManifest(codebasePath: string, indexedPaths: string[]): void;
+    getCodebaseIndexedPaths(codebasePath: string): string[];
+    setCodebaseIgnoreRulesVersion(codebasePath: string, version: number): void;
+    getCodebaseIgnoreControlSignature(codebasePath: string): string | undefined;
+    setCodebaseIgnoreControlSignature(codebasePath: string, signature: string): void;
     getCodebaseCallGraphSidecar(codebasePath: string): CallGraphSidecarInfo | undefined;
     removeCodebaseCompletely(codebasePath: string): void;
     removeIndexedCodebase(codebasePath: string): void;