@zokizuan/satori-mcp 6.1.0 → 6.2.0

package/dist/core/backend-diagnostics.d.ts

@@ -1,3 +1,4 @@
+import type { EmbeddingProviderErrorCode } from "@zokizuan/satori-core";
 export type VectorBackendDiagnosticCode = "ZILLIZ_CLUSTER_STOPPED" | "VECTOR_BACKEND_AUTH_FAILED" | "VECTOR_BACKEND_UNREACHABLE" | "VECTOR_BACKEND_TIMEOUT" | "VECTOR_BACKEND_CONNECTION_CLOSED";
 export interface VectorBackendDiagnostic {
     code: VectorBackendDiagnosticCode;
@@ -11,5 +12,21 @@ export interface VectorBackendDiagnostic {
         };
     };
 }
+export type SemanticPassFailureDiagnostic = {
+    passId: "primary" | "expanded";
+    errorName: "Error" | "TypeError" | "RangeError" | "ReferenceError" | "SyntaxError" | "AggregateError" | "EmbeddingProviderError" | "NonErrorThrow";
+    code: VectorBackendDiagnosticCode | EmbeddingProviderErrorCode | "UNCLASSIFIED_SEARCH_PASS_FAILURE";
+    classifier: "embedding_provider" | "vector_backend" | "unclassified";
+    retryable?: boolean;
+};
+export declare function buildSemanticPassFailureDiagnostic(input: {
+    passId: SemanticPassFailureDiagnostic["passId"];
+    error: unknown;
+    embeddingDiagnostic: {
+        code: EmbeddingProviderErrorCode;
+        retryable: boolean;
+    } | null;
+    vectorDiagnostic: VectorBackendDiagnostic | null;
+}): SemanticPassFailureDiagnostic;
 export declare function classifyVectorBackendError(error: unknown): VectorBackendDiagnostic | null;
 //# sourceMappingURL=backend-diagnostics.d.ts.map

package/dist/core/backend-diagnostics.js

@@ -1,3 +1,47 @@
+const ALLOWED_SEARCH_PASS_ERROR_NAMES = new Set([
+    "Error",
+    "TypeError",
+    "RangeError",
+    "ReferenceError",
+    "SyntaxError",
+    "AggregateError",
+    "EmbeddingProviderError",
+]);
+function classifySearchPassErrorName(error) {
+    if (!(error instanceof Error)) {
+        return "NonErrorThrow";
+    }
+    return ALLOWED_SEARCH_PASS_ERROR_NAMES.has(error.name)
+        ? error.name
+        : "Error";
+}
+export function buildSemanticPassFailureDiagnostic(input) {
+    const errorName = classifySearchPassErrorName(input.error);
+    if (input.embeddingDiagnostic) {
+        return {
+            passId: input.passId,
+            errorName,
+            code: input.embeddingDiagnostic.code,
+            classifier: "embedding_provider",
+            retryable: input.embeddingDiagnostic.retryable,
+        };
+    }
+    if (input.vectorDiagnostic) {
+        return {
+            passId: input.passId,
+            errorName,
+            code: input.vectorDiagnostic.code,
+            classifier: "vector_backend",
+            retryable: input.vectorDiagnostic.hints.backend.retryable,
+        };
+    }
+    return {
+        passId: input.passId,
+        errorName,
+        code: "UNCLASSIFIED_SEARCH_PASS_FAILURE",
+        classifier: "unclassified",
+    };
+}
 function collectErrorText(value, depth = 0) {
     if (depth > 2 || value == null) {
         return "";

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

@@ -84,6 +84,7 @@ export type CallGraphQueryResponse = CallGraphResponseSupported | CallGraphRespo
 export interface CallGraphDeltaPolicy {
     shouldRebuild(changedFiles: string[]): boolean;
 }
+export declare const DEFAULT_CALL_GRAPH_TEST_REFERENCE_LIMIT = 50;
 export declare class SupportedSourceDeltaPolicy implements CallGraphDeltaPolicy {
     shouldRebuild(changedFiles: string[]): boolean;
 }

package/dist/core/call-graph.js

@@ -9,7 +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;
+export 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',
 ]);

package/dist/core/handlers.d.ts

@@ -296,6 +296,7 @@ export declare class ToolHandlers {
                 searchPassCount: number;
                 searchPassSuccessCount: number;
                 searchPassFailureCount: number;
+                semanticPassFailures?: import("./backend-diagnostics.js").SemanticPassFailureDiagnostic[];
                 rerankerAttempted: boolean;
                 rerankerUsed: boolean;
                 tool?: undefined;
@@ -336,6 +337,7 @@ export declare class ToolHandlers {
                 searchPassCount: number;
                 searchPassSuccessCount: number;
                 searchPassFailureCount: number;
+                semanticPassFailures?: import("./backend-diagnostics.js").SemanticPassFailureDiagnostic[];
                 rerankerAttempted: boolean;
                 rerankerUsed: boolean;
                 tool?: undefined;

package/dist/core/handlers.js

@@ -2298,6 +2298,21 @@ export class ToolHandlers {
                 isError: true,
             };
         }
+        const parsedOperators = this.searchQuerySupport.parseSearchOperators(input.query);
+        if (parsedOperators.semanticQuery.trim().length === 0) {
+            const payload = this.buildInvalidSearchRequestPayload({
+                path: input.path,
+                query: input.query,
+                scope: input.scope,
+                groupBy: input.groupBy,
+                resultMode: input.resultMode,
+                limit: input.limit,
+            }, 'Operator-only search requires semantic text or a positive must:, path:, or lang: value.');
+            return {
+                content: [{ type: "text", text: this.stringifyToolJson(payload) }],
+                isError: true,
+            };
+        }
         const searchDiagnostics = {
             queryLength: input.query.length,
             limitRequested: input.limit,
@@ -2425,9 +2440,16 @@ export class ToolHandlers {
                             thresholdMs: SEARCH_FRESHNESS_THRESHOLD_MS,
                         });
                     }
-                    return this.syncManager.ensureFreshness(effectiveRoot, exactSourceComparisonRequired ? 0 : SEARCH_FRESHNESS_THRESHOLD_MS, preparedRead?.vectorReceipt
-                        ? { preparedVectorReceipt: preparedRead.vectorReceipt }
-                        : {});
+                    return this.syncManager.ensureFreshness(effectiveRoot, exactSourceComparisonRequired ? 0 : SEARCH_FRESHNESS_THRESHOLD_MS, {
+                        ...(preparedRead?.vectorReceipt
+                            ? { preparedVectorReceipt: preparedRead.vectorReceipt }
+                            : {}),
+                        ...(exactSourceComparisonRequired
+                            ? {
+                                exactSourceComparisonPaths: Array.from(changedFilesState.files).sort(),
+                            }
+                            : {}),
+                    });
                 }),
                 noteFreshnessMode: (mode) => {
                     searchDiagnostics.freshnessMode = mode;
@@ -2470,7 +2492,8 @@ export class ToolHandlers {
                 }
             }
             const sourceFreshnessWasEstablished = freshnessDecision.mode === 'synced'
-                || freshnessDecision.mode === 'reconciled_ignore_change';
+                || freshnessDecision.mode === 'reconciled_ignore_change'
+                || freshnessDecision.mode === 'skipped_source_unchanged';
             const checkpointWarningAlreadyPresent = frontDoorWarnings.includes(WARNING_CODES.SOURCE_FRESHNESS_CHECKPOINT_UNAVAILABLE);
             const partialIndexSearchWarnings = !sourceFreshnessWasEstablished
                 && !checkpointWarningAlreadyPresent
@@ -2487,7 +2510,6 @@ export class ToolHandlers {
             console.log(`${rootTag} Query metadata: length=${input.query.length}, requestId=${requestId}`);
             console.log(`${rootTag} Indexing status: Completed`);
             console.log(`${rootTag} 🧠 Using embedding provider: ${encoderEngine.getProvider()} for search`);
-            const parsedOperators = this.searchQuerySupport.parseSearchOperators(input.query);
             const semanticQuery = parsedOperators.semanticQuery;
             const queryPlan = this.searchQuerySupport.buildSearchQueryPlan(semanticQuery, parsedOperators);
             searchDiagnostics.routeKind = queryPlan.route.kind;
@@ -2537,6 +2559,7 @@ export class ToolHandlers {
             const initialDirtyFilesNotFreshened = initialObservedChangedFilesState.available
                 && initialObservedChangedFilesCount > 0
                 && freshnessDecision.mode !== 'synced'
+                && freshnessDecision.mode !== 'skipped_source_unchanged'
                 && freshnessDecision.mode !== 'reconciled_ignore_change';
             const initialRankingProvenance = {
                 semanticPassesUsed: [],
@@ -2755,6 +2778,14 @@ export class ToolHandlers {
                     resultMode: input.resultMode,
                     limit: input.limit
                 }, "Search backend failed: all semantic search passes failed. Retry and verify embedding/vector backends are reachable.", "not_ready", "search_backend_failed");
+                if (debugMode === 'full') {
+                    payload.hints = {
+                        ...(payload.hints || {}),
+                        debugSearch: {
+                            semanticPassFailures: execution.semanticPassFailures.map((failure) => ({ ...failure })),
+                        },
+                    };
+                }
                 return {
                     content: [{ type: "text", text: this.stringifyToolJson(payload) }],
                     isError: true,
@@ -3025,7 +3056,7 @@ export class ToolHandlers {
             includeSummary: true,
             buildEnvelope: (results, disclosure) => {
                 const recommendedNextAction = entry.recommendedActions[lookup.nextOffset] ?? null;
-                const noiseMitigationHint = this.searchQuerySupport.buildNoiseMitigationHint(entry.canonicalRoot, results.map((result) => result.target.file), entry.baseEnvelope.scope);
+                const noiseMitigationHint = this.searchQuerySupport.buildNoiseMitigationHint(entry.canonicalRoot, results.map((result) => result.target.file), entry.baseEnvelope.scope, this.searchQuerySupport.parseSearchOperators(entry.baseEnvelope.query));
                 const generatedArtifactsHint = this.buildGeneratedArtifactsVerificationHint(entry.canonicalRoot, results.map((result) => ({
                     file: result.target.file,
                     span: result.target.span,

package/dist/core/manage-indexing-handlers.js

@@ -766,6 +766,11 @@ export class ManageIndexingHandlers {
                         }
                         this.host.mutationLeaseCoordinator.publishWhileCurrent(mutationLease, publish);
                     },
+                    publicationAuthority: {
+                        ownerId: mutationLease.ownerId,
+                        generation: mutationLease.generation,
+                        operationId: mutationLease.operationId,
+                    },
                 } : {}),
             });
             if (mutationLease) {
@@ -781,16 +786,41 @@ export class ManageIndexingHandlers {
                     ...result.proof,
                     navigation: {
                         status: "unproven",
-                        basis: "call_graph_rebuild_in_progress",
+                        basis: "generation_proof_in_progress",
                     },
                 };
-                await this.host.rebuildCallGraphForIndex(absolutePath, assertMutationCurrent);
+                const proven = await this.host.context.proveIndexedGeneration(absolutePath);
+                if (!proven
+                    || proven.collectionName !== result.collectionName
+                    || proven.marker.indexedFiles !== result.indexedFiles
+                    || proven.exactPayloadCount !== result.totalChunks) {
+                    throw new Error(`Repair completion for '${absolutePath}' did not match an exact proven generation.`);
+                }
+                if (result.activatedGeneration) {
+                    const activated = result.activatedGeneration;
+                    if (activated.collectionName !== proven.collectionName
+                        || activated.markerRunId !== proven.marker.runId
+                        || activated.relationshipVersion !== this.host.runtimeFingerprint.relationshipVersion
+                        || activated.navigation.generationId !== proven.navigation.generationId
+                        || activated.navigation.sealHash !== proven.navigation.navigationSealHash
+                        || activated.navigation.symbolRegistryManifestHash
+                            !== proven.navigation.symbolRegistryManifestHash
+                        || activated.navigation.relationshipManifestHash
+                            !== proven.navigation.relationshipManifestHash) {
+                        throw new Error(`Relationship-only repair for '${absolutePath}' did not prove its activated navigation generation.`);
+                    }
+                    const checkpoint = await this.host.context.inspectSourceFreshnessCheckpoint(absolutePath, proven.collectionName, proven);
+                    if (checkpoint.status !== "valid"
+                        || checkpoint.documentDigest !== activated.sourceCheckpointDocumentDigest) {
+                        throw new Error(`Relationship-only repair for '${absolutePath}' did not preserve its source checkpoint identity.`);
+                    }
+                }
                 assertMutationCurrent?.();
                 lastRepairProof = {
                     ...result.proof,
                     navigation: {
                         status: "matched",
-                        basis: "navigation_and_call_graph_rebuilt",
+                        basis: "activated_generation_proven",
                     },
                 };
                 try {
@@ -853,7 +883,7 @@ export class ManageIndexingHandlers {
         }
         catch (error) {
             console.error("Error in handleRepairIndex:", error);
-            if (lastRepairProof?.navigation.basis === "call_graph_rebuild_in_progress") {
+            if (lastRepairProof?.navigation.basis === "generation_proof_in_progress") {
                 lastRepairProof = {
                     ...lastRepairProof,
                     navigation: {

package/dist/core/navigation-handlers.js

@@ -528,7 +528,6 @@ export class NavigationHandlers {
             const exactRegistrySymbols = findExactRegistrySymbols({
                 symbols: registryState.symbols,
                 symbolIdExact: symbolRef.symbolId,
-                symbolLabelExact: symbolRef.symbolLabel,
             });
             if (exactRegistrySymbols.length === 0) {
                 const payload = this.host.withProofDebugHint({

package/dist/core/python-call-fallback.js

@@ -140,21 +140,103 @@ function findPythonDefinitionIndexNearSpan(lines, symbol) {
     const windowEnd = Math.min(lines.length, Math.max(spanEndExclusive, startIndex + 48));
     return findPythonDefinitionIndexByName(lines, symbol.name, windowStart, windowEnd);
 }
+function isPythonDecoratorBlock(lines, startIndex, definitionIndex, indent) {
+    let delimiterDepth = 0;
+    let quote = null;
+    let tripleQuoted = false;
+    let escaped = false;
+    let expectsDecorator = true;
+    for (let index = startIndex; index < definitionIndex; index += 1) {
+        const line = lines[index] || "";
+        const trimmed = line.trim();
+        if (expectsDecorator) {
+            if (trimmed.length === 0
+                || !trimmed.startsWith("@")
+                || countPythonIndent(line) !== indent) {
+                return false;
+            }
+            expectsDecorator = false;
+        }
+        else if (trimmed.length === 0 && delimiterDepth === 0 && !tripleQuoted) {
+            return false;
+        }
+        for (let offset = 0; offset < line.length; offset += 1) {
+            const char = line[offset];
+            const nextTwo = line.slice(offset, offset + 3);
+            if (quote) {
+                if (escaped) {
+                    escaped = false;
+                    continue;
+                }
+                if (char === "\\") {
+                    escaped = true;
+                    continue;
+                }
+                if (tripleQuoted && nextTwo === quote.repeat(3)) {
+                    quote = null;
+                    tripleQuoted = false;
+                    offset += 2;
+                    continue;
+                }
+                if (!tripleQuoted && char === quote) {
+                    quote = null;
+                }
+                continue;
+            }
+            if (char === "#") {
+                break;
+            }
+            if (nextTwo === "'''" || nextTwo === "\"\"\"") {
+                quote = char;
+                tripleQuoted = true;
+                offset += 2;
+                continue;
+            }
+            if (char === "'" || char === "\"") {
+                quote = char;
+                continue;
+            }
+            if (char === "(" || char === "[" || char === "{") {
+                delimiterDepth += 1;
+                continue;
+            }
+            if (char === ")" || char === "]" || char === "}") {
+                delimiterDepth -= 1;
+                if (delimiterDepth < 0) {
+                    return false;
+                }
+            }
+        }
+        const explicitContinuation = line.trimEnd().endsWith("\\");
+        if (!quote && delimiterDepth === 0 && !explicitContinuation) {
+            expectsDecorator = true;
+        }
+        else if (quote && !tripleQuoted) {
+            return false;
+        }
+        escaped = false;
+    }
+    return expectsDecorator && delimiterDepth === 0 && quote === null;
+}
 function findPythonDecoratedDefinitionStart(lines, definitionIndex) {
     const indent = countPythonIndent(lines[definitionIndex] || "");
-    let startIndex = definitionIndex;
+    const candidates = [];
     for (let index = definitionIndex - 1; index >= 0; index -= 1) {
         const line = lines[index] || "";
         const trimmed = line.trim();
-        if (trimmed.length === 0) {
+        if (trimmed.length === 0 && candidates.length === 0) {
             break;
         }
-        if (!trimmed.startsWith("@") || countPythonIndent(line) !== indent) {
-            break;
+        if (trimmed.startsWith("@") && countPythonIndent(line) === indent) {
+            candidates.push(index);
+        }
+    }
+    for (const candidate of candidates.reverse()) {
+        if (isPythonDecoratorBlock(lines, candidate, definitionIndex, indent)) {
+            return candidate;
         }
-        startIndex = index;
     }
-    return startIndex;
+    return definitionIndex;
 }
 function findPythonSourceBackedBlockEnd(lines, definitionIndex, indent) {
     let lastContentLine = definitionIndex + 1;

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

@@ -40,8 +40,6 @@ export type RelationshipBackedCallGraphResult = {
     };
     hints?: Record<string, unknown>;
 };
-/** True when a repo-relative path looks like a test/fixture site (not production call graph signal). */
-export declare function isTestOrFixtureCallerFile(file: string): boolean;
 /**
  * Prefer a single unique suppressed inbound caller *site* file for recovery search.
  * Prefer production files when both production and test sites exist.
@@ -58,6 +56,8 @@ export declare class RelationshipBackedCallGraph {
     private sortNodes;
     private compareEdges;
     private sortEdges;
+    private sortTestReferences;
+    private buildTestReferences;
     private sortNotes;
     private mapRelationshipConfidence;
     private createNode;

package/dist/core/relationship-backed-call-graph.js

@@ -1,4 +1,5 @@
-import { compareContractStrings, getGraphNeighbors, } from "@zokizuan/satori-core";
+import { compareContractStrings, getGraphNeighbors, getRelationshipsForSymbol, isTestOrFixturePath, } from "@zokizuan/satori-core";
+import { DEFAULT_CALL_GRAPH_TEST_REFERENCE_LIMIT } from "./call-graph.js";
 import { buildSourceBackedPythonCalleeFallback, buildSourceBackedPythonCallerFallback, } from "./python-call-fallback.js";
 import { buildInboundNotesOnlySearchQuery } from "./search-response-helpers.js";
 function compareNullableNumbersAsc(a, b) {
@@ -11,24 +12,6 @@ function compareNullableStringsAsc(a, b) {
     const right = typeof b === "string" ? b : "";
     return compareContractStrings(left, right);
 }
-/** True when a repo-relative path looks like a test/fixture site (not production call graph signal). */
-export function isTestOrFixtureCallerFile(file) {
-    const normalized = file.trim().replace(/\\/g, "/");
-    if (!normalized) {
-        return false;
-    }
-    const base = normalized.split("/").pop() || normalized;
-    if (/\.(test|spec)\.[cm]?[jt]sx?$/i.test(base)) {
-        return true;
-    }
-    if (/(^|\/)(__tests__|__mocks__|fixtures|testdata|test-data)(\/|$)/i.test(normalized)) {
-        return true;
-    }
-    if (/(^|\/)tests?(\/|$)/i.test(normalized) && !/(^|\/)packages\/[^/]+\/src\//i.test(normalized)) {
-        return true;
-    }
-    return false;
-}
 /**
  * Prefer a single unique suppressed inbound caller *site* file for recovery search.
  * Prefer production files when both production and test sites exist.
@@ -49,7 +32,7 @@ export function uniqueInboundCallerSiteFile(notes) {
             continue;
         }
         allSites.add(file);
-        if (!isTestOrFixtureCallerFile(file)) {
+        if (!isTestOrFixturePath(file)) {
             productionSites.add(file);
         }
     }
@@ -76,7 +59,7 @@ export function prioritizeInboundSuppressedNotes(notes) {
             continue;
         }
         const file = typeof note.file === "string" ? note.file : "";
-        if (isTestOrFixtureCallerFile(file)) {
+        if (isTestOrFixturePath(file)) {
             testCallerNotes.push(note);
         }
         else {
@@ -138,6 +121,71 @@ export class RelationshipBackedCallGraph {
     sortEdges(edges) {
         return [...edges].sort((a, b) => this.compareEdges(a, b));
     }
+    sortTestReferences(references) {
+        return [...references].sort((a, b) => {
+            const fileCmp = compareNullableStringsAsc(a.file, b.file);
+            if (fileCmp !== 0)
+                return fileCmp;
+            const startCmp = compareNullableNumbersAsc(a.span?.startLine, b.span?.startLine);
+            if (startCmp !== 0)
+                return startCmp;
+            const labelCmp = compareNullableStringsAsc(a.symbolLabel, b.symbolLabel);
+            if (labelCmp !== 0)
+                return labelCmp;
+            const symbolCmp = compareNullableStringsAsc(a.symbolId, b.symbolId);
+            if (symbolCmp !== 0)
+                return symbolCmp;
+            const targetCmp = compareNullableStringsAsc(a.targetSymbolId, b.targetSymbolId);
+            if (targetCmp !== 0)
+                return targetCmp;
+            const siteFileCmp = compareNullableStringsAsc(a.site?.file, b.site?.file);
+            if (siteFileCmp !== 0)
+                return siteFileCmp;
+            return compareNullableNumbersAsc(a.site?.startLine, b.site?.startLine);
+        });
+    }
+    buildTestReferences(records, registry, targetSymbolId) {
+        const referencesByKey = new Map();
+        for (const record of records) {
+            if (record.type !== "TESTS"
+                || !record.sourceInstanceId
+                || record.targetInstanceId !== targetSymbolId) {
+                continue;
+            }
+            const source = registry.symbolsByInstanceId.get(record.sourceInstanceId);
+            if (!source) {
+                continue;
+            }
+            const startLine = record.span?.startLine ?? source.span.startLine;
+            const reference = {
+                file: source.file,
+                symbolId: source.symbolInstanceId,
+                symbolLabel: source.label,
+                span: {
+                    startLine: source.span.startLine,
+                    endLine: source.span.endLine,
+                },
+                site: {
+                    file: record.file,
+                    startLine,
+                    ...(record.span?.endLine ? { endLine: record.span.endLine } : {}),
+                },
+                targetSymbolId,
+                kind: "call",
+                confidence: this.mapRelationshipConfidence(record.confidence),
+            };
+            const key = [
+                reference.symbolId,
+                reference.targetSymbolId,
+                reference.kind,
+                reference.site.file,
+                reference.site.startLine,
+            ].join("\0");
+            referencesByKey.set(key, reference);
+        }
+        return this.sortTestReferences([...referencesByKey.values()])
+            .slice(0, DEFAULT_CALL_GRAPH_TEST_REFERENCE_LIMIT);
+    }
     sortNotes(notes) {
         return [...notes].sort((a, b) => {
             const fileCmp = compareNullableStringsAsc(a.file, b.file);
@@ -243,6 +291,19 @@ export class RelationshipBackedCallGraph {
         if (neighbors.status !== "ok") {
             return null;
         }
+        const testRelationshipResult = await getRelationshipsForSymbol({
+            normalizedRootPath: input.codebaseRoot,
+            generationId: input.generationId,
+            expectedSymbolRegistryManifestHash: input.registryManifestHash,
+            navigationStore: this.host.navigationStore,
+            targetInstanceId: input.resolvedSymbol.symbolInstanceId,
+            direction: "callers",
+            types: ["TESTS"],
+        });
+        if (testRelationshipResult.status !== "ok") {
+            return null;
+        }
+        const testReferences = this.buildTestReferences(testRelationshipResult.records, input.registry, input.resolvedSymbol.symbolInstanceId);
         const suppressedLowConfidenceRecords = neighbors.suppressedLowConfidenceRecords || [];
         const resolveNodeSymbol = (symbolInstanceId) => (symbolInstanceId === input.resolvedSymbol.symbolInstanceId
             ? input.resolvedSymbol
@@ -408,6 +469,7 @@ export class RelationshipBackedCallGraph {
                 nodeCount: combinedNodes.length,
                 edgeCount: combinedEdges.length,
             },
+            ...(testReferences.length > 0 ? { testReferences } : {}),
             ...(hints ? { hints } : {}),
         };
     }

package/dist/core/search-exact-fast-path.js

@@ -350,7 +350,7 @@ export async function runExactRegistryFastPath(input, host) {
         partialIndexSearchWarnings: input.partialIndexSearchWarnings,
         dirtyFilesNotFreshened: input.dirtyFilesNotFreshened,
         changedFilesBoostSkippedForLargeChangeSet: input.changedFilesBoostSkippedForLargeChangeSet,
-        buildNoiseMitigationHint: (files) => host.searchQuerySupport.buildNoiseMitigationHint(input.effectiveRoot, files, input.scope),
+        buildNoiseMitigationHint: (files) => host.searchQuerySupport.buildNoiseMitigationHint(input.effectiveRoot, files, input.scope, input.parsedOperators),
         buildGeneratedArtifactsVerificationHint: (results) => host.buildGeneratedArtifactsVerificationHint(input.effectiveRoot, results),
     });
     if (!envelope) {

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

@@ -4,7 +4,7 @@ import type { SearchCandidateSurvivalDebug, SearchDebugMode, SearchFreshnessSumm
 import type { SearchQuerySupport } from "./search-query-support.js";
 import type { SearchQueryPlan, SearchResultLike } from "./search-lexical-scoring.js";
 import type { ParsedSearchOperators } from "./search-query-planning.js";
-import type { VectorBackendDiagnostic } from "./backend-diagnostics.js";
+import { type SemanticPassFailureDiagnostic, type VectorBackendDiagnostic } from "./backend-diagnostics.js";
 import type { EmbeddingProviderDiagnostic } from "./embedding-provider-diagnostics.js";
 import type { FreshnessDecision } from "./sync.js";
 import { type RerankBudgetReason } from "./search-rerank-policy.js";
@@ -39,6 +39,7 @@ export type SearchDiagnostics = SearchProviderWorkDiagnostics & {
     searchPassCount: number;
     searchPassSuccessCount: number;
     searchPassFailureCount: number;
+    semanticPassFailures?: SemanticPassFailureDiagnostic[];
     rerankerAttempted: boolean;
     rerankerUsed: boolean;
 };
@@ -149,6 +150,7 @@ export type SearchExecutionOutcome = {
     };
     providerWork: SearchProviderWorkDiagnostics;
     candidateSurvival?: SearchCandidateSurvivalDebug;
+    semanticPassFailures: SemanticPassFailureDiagnostic[];
 } | {
     kind: "vector_backend_unavailable";
     diagnostic: VectorBackendDiagnostic;
@@ -157,6 +159,7 @@ export type SearchExecutionOutcome = {
     diagnostic: EmbeddingProviderDiagnostic;
 } | {
     kind: "all_semantic_passes_failed";
+    semanticPassFailures: SemanticPassFailureDiagnostic[];
 };
 export type SearchExecutionHost = {
     searchQuerySupport: SearchQuerySupport;

package/dist/core/search-execution.js

@@ -3,6 +3,7 @@ import { appendCoreCandidateTrace, appendSearchCandidatePass, appendSearchCandid
 import { WARNING_CODES } from "./warnings.js";
 import { buildSearchPassWarning as buildSearchPassWarningHelper, } from "./search-response-helpers.js";
 import { classifyPathCategory, resolveAgentFitMultiplier as resolveSearchAgentFitMultiplier, shouldApplyChangedFilesBoost, shouldIncludeCategoryInScope, sortSearchCandidates as sortSearchCandidatesHelper, } from "./search-ranking-policy.js";
+import { buildSemanticPassFailureDiagnostic, } from "./backend-diagnostics.js";
 import { resolveRerankFamilyKey, selectRerankCandidates, selectRerankInputWithinUtf8Budget, } from "./search-rerank-policy.js";
 import { resolveNextSearchCandidateLimit, } from './search-policy.js';
 const SEARCH_EXPANSION_MIN_PRIMARY_SCOPED_CANDIDATES = 5;
@@ -298,6 +299,7 @@ export async function runSearchExecution(input, host, searchDiagnostics) {
     const dirtyFilesNotFreshened = observedChangedFilesState.available
         && observedChangedFilesCount > 0
         && input.freshnessMode !== "synced"
+        && input.freshnessMode !== "skipped_source_unchanged"
         && input.freshnessMode !== "reconciled_ignore_change";
     const canSupplementLivePathEvidence = observedChangedFilesState.available
         && observedChangedFilesCount > 0
@@ -305,6 +307,7 @@ export async function runSearchExecution(input, host, searchDiagnostics) {
     let boostedCandidates = 0;
     let attemptsUsed = 0;
     const searchWarningsSet = new Set();
+    const semanticPassFailures = [];
     const suppressedDirtyPaths = new Set();
     const representedDirtyPaths = new Set();
     const passesUsed = new Set();
@@ -438,16 +441,23 @@ export async function runSearchExecution(input, host, searchDiagnostics) {
                 passesUsed.add(passDescriptor.id);
                 continue;
             }
-            if (passResult.status === "rejected") {
-                embeddingProviderDiagnostic ?? (embeddingProviderDiagnostic = host.classifyEmbeddingProviderError(passResult.reason));
-                if (embeddingProviderDiagnostic === null && vectorBackendDiagnostic === null) {
-                    vectorBackendDiagnostic = host.classifyVectorBackendError(passResult.reason);
-                }
-            }
+            const passEmbeddingDiagnostic = host.classifyEmbeddingProviderError(passResult.reason);
+            const passVectorDiagnostic = passEmbeddingDiagnostic
+                ? null
+                : host.classifyVectorBackendError(passResult.reason);
+            embeddingProviderDiagnostic ?? (embeddingProviderDiagnostic = passEmbeddingDiagnostic);
+            vectorBackendDiagnostic ?? (vectorBackendDiagnostic = passVectorDiagnostic);
+            semanticPassFailures.push(buildSemanticPassFailureDiagnostic({
+                passId: passDescriptor.id,
+                error: passResult.reason,
+                embeddingDiagnostic: passEmbeddingDiagnostic,
+                vectorDiagnostic: passVectorDiagnostic,
+            }));
             searchWarningsSet.add(buildSearchPassWarningHelper(passDescriptor.id));
         }
         searchDiagnostics.searchPassSuccessCount += successfulPasses.length;
         searchDiagnostics.searchPassFailureCount += passDescriptors.length - successfulPasses.length;
+        searchDiagnostics.semanticPassFailures = semanticPassFailures.map((failure) => ({ ...failure }));
         if (successfulPasses.length === 0) {
             if (embeddingProviderDiagnostic) {
                 return {
@@ -461,7 +471,10 @@ export async function runSearchExecution(input, host, searchDiagnostics) {
                     diagnostic: vectorBackendDiagnostic,
                 };
             }
-            return { kind: "all_semantic_passes_failed" };
+            return {
+                kind: "all_semantic_passes_failed",
+                semanticPassFailures,
+            };
         }
         const byChunkKey = new Map();
         const attemptFilterSummary = buildEmptyFilterSummary();
@@ -876,6 +889,7 @@ export async function runSearchExecution(input, host, searchDiagnostics) {
             semanticExpansionAttempted: searchDiagnostics.semanticExpansionAttempted,
             semanticExpansionReason: searchDiagnostics.semanticExpansionReason,
         },
+        semanticPassFailures,
         ...(candidateSurvival ? { candidateSurvival } : {}),
     };
 }

package/dist/core/search-frontdoor.js

@@ -28,6 +28,7 @@ function buildReadinessWarnings(host, state) {
 }
 function freshnessDecisionPreservesAuthority(decision) {
     return decision.mode === 'skipped_recent'
+        || decision.mode === 'skipped_source_unchanged'
         || decision.mode === 'skipped_source_checkpoint_unavailable';
 }
 function buildBlockedReadinessPayload(state, searchContext, host) {

package/dist/core/search-query-planning.js

@@ -57,18 +57,17 @@ function unquoteOperatorValue(value) {
     return trimmed;
 }
 function deriveOperatorOnlySemanticQuery(operators) {
-    if (operators.must.length !== 1) {
-        return null;
+    const mustTerms = operators.must.map((value) => value.trim()).filter(Boolean);
+    if (mustTerms.length > 0) {
+        return mustTerms.join(" ");
     }
-    const mustValue = operators.must[0].trim();
-    if (/\s/.test(mustValue)) {
-        return null;
+    const pathTerms = operators.path.map((value) => value.trim()).filter(Boolean);
+    if (pathTerms.length > 0) {
+        return pathTerms.join(" ");
     }
-    const symbolInstanceIdLike = /^syminst_[a-f0-9]{32}$/i.test(mustValue);
-    const identifierLike = /^[A-Za-z_$][A-Za-z0-9_$]*(?:(?:[.#:/-]|::)[A-Za-z_$][A-Za-z0-9_$]*)*$/.test(mustValue);
-    const strongIdentifierSignal = /[A-Z_]/.test(mustValue) || /(?:\.|::|#|\/)/.test(mustValue);
-    if (symbolInstanceIdLike || (identifierLike && strongIdentifierSignal)) {
-        return mustValue;
+    const languageTerms = operators.lang.map((value) => value.trim()).filter(Boolean);
+    if (languageTerms.length > 0) {
+        return languageTerms.join(" ");
     }
     return null;
 }
@@ -151,7 +150,7 @@ export function parseSearchOperators(query) {
     const semanticParts = [semanticFromPrefix, semanticSuffix].filter((part) => part.length > 0);
     operators.semanticQuery = semanticParts.length > 0
         ? semanticParts.join("\n")
-        : (deriveOperatorOnlySemanticQuery(operators) || trimmedQuery);
+        : (deriveOperatorOnlySemanticQuery(operators) || "");
     return operators;
 }
 function tokenizeLexicalTerms(tokens) {

package/dist/core/search-query-support.d.ts

@@ -99,7 +99,7 @@ export declare class SearchQuerySupport {
     private loadRootGitignoreMatcher;
     private patternMatchesAnyPath;
     private filterNoiseHintPatternsByRootGitignore;
-    buildNoiseMitigationHint(codebaseRoot: string, filesInOrder: string[], scope: SearchScope): SearchNoiseMitigationHint | undefined;
+    buildNoiseMitigationHint(codebaseRoot: string, filesInOrder: string[], scope: SearchScope, parsedOperators: Pick<ParsedSearchOperators, "path">): SearchNoiseMitigationHint | undefined;
     parseSearchOperators(query: string): ParsedSearchOperators;
     buildSearchQueryPlan(semanticQuery: string, parsedOperators?: ParsedSearchOperators): SearchQueryPlan;
     hasTokenBoundaryMatch(field: string, term: string): boolean;

package/dist/core/search-query-support.js

@@ -912,8 +912,8 @@ export class SearchQuerySupport {
             coveredByRootGitignore,
         };
     }
-    buildNoiseMitigationHint(codebaseRoot, filesInOrder, scope) {
-        if (scope === 'docs') {
+    buildNoiseMitigationHint(codebaseRoot, filesInOrder, scope, parsedOperators) {
+        if (scope === 'docs' || scope === 'runtime' || parsedOperators.path.length > 0) {
             return undefined;
         }
         if (!Array.isArray(filesInOrder) || filesInOrder.length === 0) {

package/dist/core/search-response-envelopes.d.ts

@@ -1,6 +1,6 @@
 import type { SearchGroupBy, SearchScope } from "./search-constants.js";
 import type { FreshnessDecision } from "./sync.js";
-import type { SearchChunkResult, SearchDebugHint, SearchFreshnessDebugHint, SearchFreshnessSummary, SearchGroupResult, SearchDisclosureSummary, SearchRankingDebugHint, SearchGroupedResultV2, SearchResponseEnvelope } from "./search-types.js";
+import type { SearchChunkResult, SearchDebugHint, SearchFreshnessDebugHint, SearchFreshnessSummary, SearchGroupResult, SearchDisclosureSummary, SearchRankingDebugHint, SearchPassFailureDebugHint, SearchGroupedResultV2, SearchResponseEnvelope } from "./search-types.js";
 import type { CompletionProbeDebugHint } from "./tracked-root-readiness.js";
 type SearchResponseCommonInput = {
     codebaseRoot: string;
@@ -13,7 +13,7 @@ type SearchResponseCommonInput = {
     freshnessSummary: SearchFreshnessSummary;
     warnings: string[];
     debugSummary?: NonNullable<NonNullable<SearchResponseEnvelope["hints"]>["debugSummary"]>;
-    debugSearch?: SearchDebugHint | SearchRankingDebugHint | SearchFreshnessDebugHint;
+    debugSearch?: SearchDebugHint | SearchRankingDebugHint | SearchFreshnessDebugHint | SearchPassFailureDebugHint;
     proofDebugHint?: CompletionProbeDebugHint;
     noiseMitigationHint?: unknown;
     generatedArtifactsHint?: unknown;

package/dist/core/search-result-finalization.js

@@ -5,7 +5,7 @@ import { buildSearchDebugSummary, buildSearchGroupRecommendedAction, SEARCH_GROU
 import { appendGroupedCandidateStage, appendSearchCandidateRemoval, appendSearchCandidateStage, } from "./search-candidate-survival.js";
 import { projectGroupedDisclosure } from "./search-disclosure.js";
 export async function finalizeSearchResults(input, host) {
-    let { scored, operatorSummary, filterSummary, trackedLexicalDebug, candidateLimit, diagnosticCandidateLimit, attemptsUsed, searchWarnings, passesUsed, backendScoreKinds, exactMatchPinningApplied, boostedCandidates, changedFilesState, debugChangedFilesState, changedFilesCount, changedFilesBoostSkippedForLargeChangeSet, rankingProvenance, rerankerAttempted, rerankerApplied, skippedByExactPin, rerankerFailurePhase, rerankerCandidatesIn, rerankerCandidatesReranked, rerankerFamilyCount, rerankerSupplementalCandidates, rerankerCandidatePoolCount, rerankerCandidateBudget, rerankerBudgetReason, rerankerByteBudgetOmittedCandidates, semanticExpansion, providerWork, candidateSurvival, } = input.execution;
+    let { scored, operatorSummary, filterSummary, trackedLexicalDebug, candidateLimit, diagnosticCandidateLimit, attemptsUsed, searchWarnings, passesUsed, backendScoreKinds, exactMatchPinningApplied, boostedCandidates, changedFilesState, debugChangedFilesState, changedFilesCount, changedFilesBoostSkippedForLargeChangeSet, rankingProvenance, rerankerAttempted, rerankerApplied, skippedByExactPin, rerankerFailurePhase, rerankerCandidatesIn, rerankerCandidatesReranked, rerankerFamilyCount, rerankerSupplementalCandidates, rerankerCandidatePoolCount, rerankerCandidateBudget, rerankerBudgetReason, rerankerByteBudgetOmittedCandidates, semanticExpansion, providerWork, candidateSurvival, semanticPassFailures, } = input.execution;
     let freshnessSummary = input.freshnessSummary;
     let finalizedSearchWarnings = Array.from(new Set([
         ...searchWarnings,
@@ -47,6 +47,9 @@ export async function finalizeSearchResults(input, host) {
             candidatesWithLexicalEvidence: providerWork.candidatesWithLexicalEvidence,
             candidatesWithCurrentSourceEvidence: providerWork.candidatesWithCurrentSourceEvidence,
         },
+        ...(semanticPassFailures.length > 0 ? {
+            semanticPassFailures: semanticPassFailures.map((failure) => ({ ...failure })),
+        } : {}),
         semanticExpansion,
         rankingProvenance,
         ...(trackedLexicalDebug ? { trackedLexical: trackedLexicalDebug } : {}),
@@ -200,7 +203,7 @@ export async function finalizeSearchResults(input, host) {
             debugMode: input.debugMode,
             now: host.now,
         });
-        const noiseMitigationHint = host.searchQuerySupport.buildNoiseMitigationHint(input.effectiveRoot, rawResults.map((result) => result.file), input.scope);
+        const noiseMitigationHint = host.searchQuerySupport.buildNoiseMitigationHint(input.effectiveRoot, rawResults.map((result) => result.file), input.scope, input.parsedOperators);
         const generatedArtifactsHint = host.buildGeneratedArtifactsVerificationHint(input.effectiveRoot, rawResults.map((result) => ({
             file: result.file,
             span: result.span,
@@ -347,7 +350,7 @@ export async function finalizeSearchResults(input, host) {
         includeSummary: input.disclosureLimit < input.limit
             || completeDisclosureOrder.length > input.limit,
         buildEnvelope: (results, disclosure) => {
-            const noiseMitigationHint = host.searchQuerySupport.buildNoiseMitigationHint(input.effectiveRoot, results.map((result) => result.target.file), input.scope);
+            const noiseMitigationHint = host.searchQuerySupport.buildNoiseMitigationHint(input.effectiveRoot, results.map((result) => result.target.file), input.scope, input.parsedOperators);
             const generatedArtifactsHint = host.buildGeneratedArtifactsVerificationHint(input.effectiveRoot, results.map((result) => ({
                 file: result.target.file,
                 span: result.target.span,

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

@@ -4,6 +4,7 @@ import { SearchGroupBy, SearchNoiseCategory, SearchRankingMode, SearchResultMode
 import { FingerprintSource, IndexFingerprint } from "../config.js";
 import type { SearchRouteContract } from "./search-lexical-scoring.js";
 import type { RerankBudgetReason } from "./search-rerank-policy.js";
+import type { SemanticPassFailureDiagnostic } from "./backend-diagnostics.js";
 export type StalenessBucket = "fresh" | "aging" | "stale" | "unknown";
 export declare const SEARCH_RESPONSE_FORMAT_VERSION: 2;
 export interface SearchSpan {
@@ -304,6 +305,7 @@ export interface SearchDebugHint {
         rrfK: number;
     };
     providerWork: SearchProviderWorkDebugHint;
+    semanticPassFailures?: SemanticPassFailureDiagnostic[];
     candidateSurvival?: SearchCandidateSurvivalDebug;
     semanticExpansion?: {
         attempted: boolean;
@@ -463,12 +465,13 @@ export interface SearchDebugHint {
         };
     };
 }
-export type SearchRankingDebugHint = Pick<SearchDebugHint, "route" | "queryIntent" | "retrieval" | "mcpFusion" | "providerWork" | "semanticExpansion" | "rankingProvenance" | "trackedLexical" | "exactRegistry" | "passesUsed" | "candidateLimit" | "mustRetry" | "operatorSummary" | "filterSummary" | "diversitySummary" | "changedFilesBoost" | "rerank">;
+export type SearchRankingDebugHint = Pick<SearchDebugHint, "route" | "queryIntent" | "retrieval" | "mcpFusion" | "providerWork" | "semanticPassFailures" | "semanticExpansion" | "rankingProvenance" | "trackedLexical" | "exactRegistry" | "passesUsed" | "candidateLimit" | "mustRetry" | "operatorSummary" | "filterSummary" | "diversitySummary" | "changedFilesBoost" | "rerank">;
 export type SearchFreshnessDebugHint = Pick<SearchDebugHint, "phaseTimingsMs" | "readiness" | "changedCode">;
+export type SearchPassFailureDebugHint = Pick<SearchDebugHint, "semanticPassFailures">;
 export interface SearchResponseHints extends Record<string, unknown> {
     version?: 1;
     noiseMitigation?: SearchNoiseMitigationHint;
-    debugSearch?: SearchDebugHint | SearchRankingDebugHint | SearchFreshnessDebugHint;
+    debugSearch?: SearchDebugHint | SearchRankingDebugHint | SearchFreshnessDebugHint | SearchPassFailureDebugHint;
     debugSummary?: {
         retrieval: string;
         freshness: FreshnessDecision["mode"] | "skipped_requires_reindex" | "skipped_indexing" | "unknown";

package/dist/core/snapshot.d.ts

@@ -106,6 +106,12 @@ export declare class SnapshotManager {
     getCodebaseStatus(codebasePath: string): CodebaseInfo['status'] | 'not_found';
     getCodebaseInfo(codebasePath: string): CodebaseInfo | undefined;
     getLatestOperation(codebasePath: string): IndexOperationReceipt | undefined;
+    /**
+     * Read the latest operation directly from the durable shared snapshot.
+     * Cross-process waiters use this instead of trusting their startup cache.
+     */
+    observeDurableLatestOperation(codebasePath: string): IndexOperationReceipt | undefined;
+    operationMatchesRuntimeFingerprint(receipt: IndexOperationReceipt): boolean;
     setLatestOperation(codebasePath: string, receipt: IndexOperationReceipt): void;
     startOperation(lease: RootMutationLease): IndexOperationReceipt;
     transitionOperation(lease: RootMutationLease, phase: IndexOperationPhase): IndexOperationReceipt;

package/dist/core/snapshot.js

@@ -1175,6 +1175,17 @@ export class SnapshotManager {
         const receipt = this.latestOperations.get(codebasePath);
         return receipt ? structuredClone(receipt) : undefined;
     }
+    /**
+     * Read the latest operation directly from the durable shared snapshot.
+     * Cross-process waiters use this instead of trusting their startup cache.
+     */
+    observeDurableLatestOperation(codebasePath) {
+        const receipt = this.readOperationMapFromDisk().get(codebasePath);
+        return receipt ? structuredClone(receipt) : undefined;
+    }
+    operationMatchesRuntimeFingerprint(receipt) {
+        return fingerprintsEqual(receipt.runtimeFingerprint, this.runtimeFingerprint);
+    }
     setLatestOperation(codebasePath, receipt) {
         if (!this.isValidOperationReceipt(receipt, codebasePath)) {
             throw new Error(`Invalid operation receipt for '${codebasePath}'.`);

package/dist/core/sync.d.ts

@@ -8,8 +8,10 @@ interface SyncManagerOptions {
     now?: () => number;
     onSyncCompleted?: (codebasePath: string, stats: SyncStats, assertMutationCurrent: () => void) => Promise<void> | void;
     mutationLeaseCoordinator?: MutationLeaseCoordinator;
+    crossProcessJoinTimeoutMs?: number;
+    crossProcessJoinPollMs?: number;
 }
-export type FreshnessDecisionMode = 'synced' | 'skipped_recent' | 'coalesced' | 'skipped_indexing' | 'skipped_requires_reindex' | 'skipped_source_checkpoint_unavailable' | 'skipped_mutation_in_progress' | 'skipped_missing_path' | 'reconciled_ignore_change' | 'ignore_reload_failed';
+export type FreshnessDecisionMode = 'synced' | 'skipped_recent' | 'skipped_source_unchanged' | 'coalesced' | 'skipped_indexing' | 'skipped_requires_reindex' | 'skipped_source_checkpoint_unavailable' | 'skipped_mutation_in_progress' | 'skipped_missing_path' | 'reconciled_ignore_change' | 'ignore_reload_failed';
 export interface FreshnessDecision {
     mode: FreshnessDecisionMode;
     checkedAt: string;
@@ -83,6 +85,7 @@ interface EnsureFreshnessOptions {
     skipIgnoreControlCheck?: boolean;
     mutationLease?: RootMutationLease;
     preparedVectorReceipt?: ProvenVectorGenerationReceipt;
+    exactSourceComparisonPaths?: readonly string[];
 }
 export declare class SyncOperationError extends Error {
     readonly operation: IndexOperationReceipt | undefined;
@@ -115,6 +118,8 @@ export declare class SyncManager {
     private readonly now;
     private readonly onSyncCompleted?;
     private readonly mutationLeaseCoordinator?;
+    private readonly crossProcessJoinTimeoutMs;
+    private readonly crossProcessJoinPollMs;
     constructor(context: Context, snapshotManager: SnapshotManager, options?: SyncManagerOptions);
     private bumpFreshnessEpoch;
     getPreparedReadObservation(codebasePath: string): PreparedReadObservationResult;
@@ -132,6 +137,7 @@ export declare class SyncManager {
     private runIgnoreReconcile;
     private reconcileIgnoreRulesChange;
     private syncCodebase;
+    private joinCrossProcessSync;
     handleSyncIndex(): Promise<void>;
     startBackgroundSync(): void;
     stopBackgroundSync(): void;

package/dist/core/sync.js

@@ -8,6 +8,8 @@ import { BACKGROUND_FRESHNESS_THRESHOLD_MS, BACKGROUND_SYNC_INITIAL_DELAY_MS, BA
 import { formatMutationLeaseBlockedMessage, } from "./mutation-lease.js";
 // v1 policy: only root-level control files trigger index-policy reconciliation.
 const IGNORE_RULE_CONTROL_FILES = new Set(['.satoriignore', '.gitignore', 'satori.toml']);
+const DEFAULT_CROSS_PROCESS_JOIN_TIMEOUT_MS = 15000;
+const DEFAULT_CROSS_PROCESS_JOIN_POLL_MS = 25;
 function errorMessage(error, fallback = "unknown_error") {
     if (error instanceof Error && error.message) {
         return error.message;
@@ -60,6 +62,8 @@ export class SyncManager {
         this.now = options.now || (() => Date.now());
         this.onSyncCompleted = options.onSyncCompleted;
         this.mutationLeaseCoordinator = options.mutationLeaseCoordinator;
+        this.crossProcessJoinTimeoutMs = Math.max(1, options.crossProcessJoinTimeoutMs ?? DEFAULT_CROSS_PROCESS_JOIN_TIMEOUT_MS);
+        this.crossProcessJoinPollMs = Math.max(1, options.crossProcessJoinPollMs ?? DEFAULT_CROSS_PROCESS_JOIN_POLL_MS);
     }
     bumpFreshnessEpoch(codebasePath) {
         this.freshnessEpochs.set(codebasePath, (this.freshnessEpochs.get(codebasePath) ?? 0) + 1);
@@ -329,6 +333,20 @@ export class SyncManager {
                 }
             }
         }
+        const exactSourceComparisonPaths = options.exactSourceComparisonPaths;
+        if (exactSourceComparisonPaths && exactSourceComparisonPaths.length > 0) {
+            const compareSourcePaths = this.context.compareSourcePathsToFreshnessCheckpoint;
+            if (typeof compareSourcePaths === 'function') {
+                const comparison = await compareSourcePaths.call(this.context, codebasePath, exactSourceComparisonPaths, options.preparedVectorReceipt);
+                if (comparison.status === 'matches') {
+                    return {
+                        mode: 'skipped_source_unchanged',
+                        checkedAt,
+                        thresholdMs,
+                    };
+                }
+            }
+        }
         // 2. Throttling: Skip if recently synced
         const lastSync = this.lastSyncTimes.get(codebasePath) || 0;
         const timeSince = checkedAtMs - lastSync;
@@ -347,7 +365,9 @@ export class SyncManager {
         this.bumpFreshnessEpoch(codebasePath);
         const syncPromise = (async () => {
             try {
-                return await this.syncCodebase(codebasePath, options.mutationLease, currentIgnoreControlSignature);
+                return await this.syncCodebase(codebasePath, options.mutationLease, currentIgnoreControlSignature, {
+                    exactSourceComparisonPaths: options.exactSourceComparisonPaths,
+                });
             }
             catch (e) {
                 // Log and rethrow to allow callers to handle/see failure
@@ -386,6 +406,7 @@ export class SyncManager {
             } : undefined,
             activeMutation: outcome.activeMutation,
             operation: outcome.operation,
+            errorMessage: outcome.errorMessage,
         };
     }
     async runIgnoreReconcile(codebasePath, coalescedEdits = 1, nextIgnoreControlSignature, existingLease) {
@@ -576,7 +597,7 @@ export class SyncManager {
             };
         }
     }
-    async syncCodebase(codebasePath, existingLease, currentIgnoreControlSignature) {
+    async syncCodebase(codebasePath, existingLease, currentIgnoreControlSignature, joinRequest = {}) {
         if (this.snapshotManager.getCodebaseStatus(codebasePath) === 'indexing') {
             console.log(`[SYNC] ⏭️  Skipping sync for '${codebasePath}' because indexing is active.`);
             return { mode: 'skipped_indexing' };
@@ -595,6 +616,9 @@ export class SyncManager {
             else {
                 const acquired = this.mutationLeaseCoordinator.acquire(codebasePath, 'sync');
                 if (!acquired.acquired) {
+                    if (acquired.activeLease.action === 'sync') {
+                        return this.joinCrossProcessSync(codebasePath, acquired.activeLease, joinRequest);
+                    }
                     return { mode: 'skipped_mutation_in_progress', activeMutation: acquired.activeLease };
                 }
                 lease = acquired.lease;
@@ -778,6 +802,164 @@ export class SyncManager {
             }
         }
     }
+    async joinCrossProcessSync(codebasePath, activeLease, request) {
+        const observeOperation = this.snapshotManager.observeDurableLatestOperation;
+        const matchesRuntime = this.snapshotManager.operationMatchesRuntimeFingerprint;
+        if (!this.mutationLeaseCoordinator
+            || typeof observeOperation !== 'function'
+            || typeof matchesRuntime !== 'function') {
+            return {
+                mode: 'skipped_mutation_in_progress',
+                activeMutation: activeLease,
+            };
+        }
+        const deadline = Date.now() + this.crossProcessJoinTimeoutMs;
+        let lastOperation;
+        while (Date.now() <= deadline) {
+            const operation = observeOperation.call(this.snapshotManager, codebasePath);
+            if (operation
+                && operation.id === activeLease.operationId
+                && operation.generation === activeLease.generation
+                && operation.action === 'sync'
+                && operation.canonicalRoot === activeLease.canonicalRoot) {
+                lastOperation = operation;
+                if (!matchesRuntime.call(this.snapshotManager, operation)) {
+                    return {
+                        mode: 'coalesced',
+                        activeMutation: activeLease,
+                        operation,
+                        errorMessage: 'The in-flight sync uses an incompatible runtime fingerprint.',
+                    };
+                }
+                if (operation.phase === 'failed' || operation.phase === 'blocked') {
+                    return {
+                        mode: 'coalesced',
+                        activeMutation: activeLease,
+                        operation,
+                        errorMessage: `The joined sync ended in terminal phase '${operation.phase}'.`,
+                    };
+                }
+                if (operation.phase === 'completed') {
+                    let checkpoint = await this.inspectSourceFreshnessCheckpoint(codebasePath);
+                    if (!checkpoint || checkpoint.status !== 'valid') {
+                        return {
+                            mode: 'coalesced',
+                            activeMutation: activeLease,
+                            operation,
+                            errorMessage: 'The joined sync completed without a proven active source checkpoint.',
+                        };
+                    }
+                    const registeredObservation = this.context.getRegisteredSourceFreshnessCheckpointObservation?.(codebasePath);
+                    if (registeredObservation !== checkpoint.observationToken
+                        && typeof this.context.recreateSynchronizerForCodebase === 'function') {
+                        try {
+                            await this.context.recreateSynchronizerForCodebase(codebasePath, undefined, undefined, { requireAuthorityCheckpoint: true });
+                        }
+                        catch {
+                            return {
+                                mode: 'coalesced',
+                                activeMutation: activeLease,
+                                operation,
+                                errorMessage: 'The joined sync completed, but this runtime could not bind its source checkpoint to the active publication.',
+                            };
+                        }
+                        checkpoint = await this.inspectSourceFreshnessCheckpoint(codebasePath);
+                        if (!checkpoint || checkpoint.status !== 'valid') {
+                            return {
+                                mode: 'coalesced',
+                                activeMutation: activeLease,
+                                operation,
+                                errorMessage: 'The joined sync source checkpoint changed while this runtime was binding it.',
+                            };
+                        }
+                        if (this.context.getRegisteredSourceFreshnessCheckpointObservation?.(codebasePath)
+                            !== checkpoint.observationToken) {
+                            return {
+                                mode: 'coalesced',
+                                activeMutation: activeLease,
+                                operation,
+                                errorMessage: 'The joined sync source checkpoint did not bind to the active publication.',
+                            };
+                        }
+                    }
+                    const paths = request.exactSourceComparisonPaths;
+                    if (paths && paths.length > 0) {
+                        const compareSourcePaths = this.context.compareSourcePathsToFreshnessCheckpoint;
+                        if (typeof compareSourcePaths !== 'function') {
+                            return {
+                                mode: 'coalesced',
+                                activeMutation: activeLease,
+                                operation,
+                                errorMessage: 'The joined sync cannot prove the requested source observation.',
+                            };
+                        }
+                        const comparison = await compareSourcePaths.call(this.context, codebasePath, paths);
+                        if (comparison.status !== 'matches') {
+                            return {
+                                mode: 'coalesced',
+                                activeMutation: activeLease,
+                                operation,
+                                errorMessage: `The joined sync did not prove the requested source observation (${comparison.status}).`,
+                            };
+                        }
+                    }
+                    const finalOperation = observeOperation.call(this.snapshotManager, codebasePath);
+                    if (!finalOperation
+                        || finalOperation.id !== operation.id
+                        || finalOperation.generation !== operation.generation
+                        || finalOperation.phase !== 'completed') {
+                        return {
+                            mode: 'coalesced',
+                            activeMutation: activeLease,
+                            ...(finalOperation ? { operation: finalOperation } : { operation }),
+                            errorMessage: 'The durable sync authority changed before the joined result could be accepted.',
+                        };
+                    }
+                    this.sourceCheckpointStatuses.set(codebasePath, 'valid');
+                    this.sourceCheckpointObservations.set(codebasePath, checkpoint.observationToken);
+                    this.lastSyncTimes.set(codebasePath, this.now());
+                    return {
+                        mode: 'coalesced',
+                        activeMutation: activeLease,
+                        operation,
+                    };
+                }
+            }
+            else if (operation && operation.generation >= activeLease.generation) {
+                return {
+                    mode: 'coalesced',
+                    activeMutation: activeLease,
+                    operation,
+                    errorMessage: 'The durable sync operation no longer matches the active mutation lease.',
+                };
+            }
+            const currentLease = this.mutationLeaseCoordinator.getActiveLease(codebasePath);
+            if (!currentLease
+                || currentLease.operationId !== activeLease.operationId
+                || currentLease.generation !== activeLease.generation) {
+                const terminal = observeOperation.call(this.snapshotManager, codebasePath);
+                if (terminal?.id === activeLease.operationId
+                    && terminal.generation === activeLease.generation
+                    && terminal.phase === 'completed') {
+                    lastOperation = terminal;
+                    continue;
+                }
+                return {
+                    mode: 'coalesced',
+                    activeMutation: activeLease,
+                    ...(terminal ? { operation: terminal } : lastOperation ? { operation: lastOperation } : {}),
+                    errorMessage: 'The in-flight sync lost its durable owner before proving completion.',
+                };
+            }
+            await new Promise((resolve) => setTimeout(resolve, this.crossProcessJoinPollMs));
+        }
+        return {
+            mode: 'coalesced',
+            activeMutation: activeLease,
+            ...(lastOperation ? { operation: lastOperation } : {}),
+            errorMessage: 'Timed out waiting for the in-flight sync to prove completion.',
+        };
+    }
     async handleSyncIndex() {
         const indexedCodebases = this.snapshotManager.getIndexedCodebases();
         if (indexedCodebases.length === 0)

package/dist/core/tool-response-builders.js

@@ -250,6 +250,7 @@ export class ToolResponseBuilders {
                 return null;
             case "synced":
             case "skipped_recent":
+            case "skipped_source_unchanged":
             case "skipped_source_checkpoint_unavailable":
             case "reconciled_ignore_change":
             case "skipped_mutation_in_progress":

package/dist/tools/search_codebase.js

@@ -202,6 +202,13 @@ const buildSearchSchema = (ctx) => z.object({
             message: "disclosureLimit cannot exceed limit.",
         });
     }
+    if (parseSearchOperators(value.query).semanticQuery.trim().length === 0) {
+        refinementContext.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["query"],
+            message: "Operator-only search requires semantic text or a positive must:, path:, or lang: value.",
+        });
+    }
 });
 export const searchCodebaseTool = {
     name: "search_codebase",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-mcp",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Repo-aware MCP tools for AI coding agents: intent search, symbol navigation, advisory call graphs, exact reads, and freshness-aware recovery.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "jsonc-parser": "^3.3.1",
     "zod": "^3.25.55",
     "zod-to-json-schema": "^3.25.1",
-    "@zokizuan/satori-core": "3.0.0"
+    "@zokizuan/satori-core": "3.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",