@zokizuan/satori-mcp 4.11.13 → 4.11.16

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

@@ -2,7 +2,7 @@ import * as fs from "fs";
 import * as crypto from "node:crypto";
 import { COLLECTION_LIMIT_MESSAGE, deleteCollectionWithVerification, RemoteCollectionDeletePendingError, } from "@zokizuan/satori-core";
 import { classifyVectorBackendError, } from "./backend-diagnostics.js";
-import { ensureAbsolutePath, trackCodebasePath } from "../utils.js";
+import { absolutePathOrRaw, requireAbsoluteFilesystemPath, trackCodebasePath } from "../utils.js";
 function isMatchingVerifiedFingerprint(info, runtimeFingerprint) {
     if (info?.fingerprintSource !== "verified") {
         return undefined;
@@ -144,7 +144,11 @@ export class ManageIndexingHandlers {
         const requestedDropCollection = typeof zillizDropCollection === "string" ? zillizDropCollection.trim() : undefined;
         let dropSummaryLine = "";
         try {
-            const absolutePath = ensureAbsolutePath(codebasePath);
+            const absolutePathResult = requireAbsoluteFilesystemPath(codebasePath, "path");
+            if (!absolutePathResult.ok) {
+                return this.host.manageResponse(manageAction, codebasePath, "error", absolutePathResult.message, preflightOptions);
+            }
+            const absolutePath = absolutePathResult.absolutePath;
             if (!fs.existsSync(absolutePath)) {
                 return this.host.manageResponse(manageAction, absolutePath, "error", `Error: Path '${absolutePath}' does not exist. Original input: '${codebasePath}'`, preflightOptions);
             }
@@ -314,7 +318,7 @@ export class ManageIndexingHandlers {
             const ignoreInfo = customIgnorePatterns.length > 0
                 ? `\nUsing ${customIgnorePatterns.length} custom ignore patterns: ${customIgnorePatterns.join(", ")}`
                 : "";
-            return this.host.manageResponse(manageAction, absolutePath, "ok", `Started background indexing for codebase '${absolutePath}'.${pathInfo}${dropSummaryLine}${extensionInfo}${ignoreInfo}\n\nIndexing is running in the background. You can search the codebase while indexing is in progress, but results may be incomplete until indexing completes.`, preflightOptions);
+            return this.host.manageResponse(manageAction, absolutePath, "ok", `Started background indexing for codebase '${absolutePath}'.${pathInfo}${dropSummaryLine}${extensionInfo}${ignoreInfo}\n\nIndexing is running in the background. Search and navigation are blocked until indexing completes. Poll manage_index with {"action":"status","path":"${absolutePath}"} (or wait for completion); do not search for partial results while status is indexing.`, preflightOptions);
         }
         catch (error) {
             console.error("Error in handleIndexCodebase:", error);
@@ -325,14 +329,18 @@ export class ManageIndexingHandlers {
                 const humanText = preservesLocalState
                     ? `${vectorBackendDiagnostic.message} ${errorMessage}`
                     : vectorBackendDiagnostic.message;
-                return this.host.manageVectorBackendResponse(manageAction, ensureAbsolutePath(codebasePath), vectorBackendDiagnostic, humanText);
+                return this.host.manageVectorBackendResponse(manageAction, absolutePathOrRaw(codebasePath), vectorBackendDiagnostic, humanText);
             }
-            return this.host.manageResponse(manageAction, ensureAbsolutePath(codebasePath), "error", `Error starting indexing: ${formatUnknownError(error)}`, preflightOptions);
+            return this.host.manageResponse(manageAction, absolutePathOrRaw(codebasePath), "error", `Error starting indexing: ${formatUnknownError(error)}`, preflightOptions);
         }
     }
     async handleReindexCodebase(args) {
         const { path: codebasePath, customExtensions, ignorePatterns, zillizDropCollection, allowUnnecessaryReindex } = args;
-        const absolutePath = ensureAbsolutePath(codebasePath);
+        const absolutePathResult = requireAbsoluteFilesystemPath(codebasePath, "path");
+        if (!absolutePathResult.ok) {
+            return this.host.manageResponse("reindex", codebasePath, "error", absolutePathResult.message);
+        }
+        const absolutePath = absolutePathResult.absolutePath;
         const runtimeOwnerConflict = await this.host.buildRuntimeOwnerConflictResponseIfBlocked("reindex", absolutePath);
         if (runtimeOwnerConflict) {
             return runtimeOwnerConflict;
@@ -374,7 +382,11 @@ export class ManageIndexingHandlers {
         }
         let absolutePath = codebasePath;
         try {
-            absolutePath = ensureAbsolutePath(codebasePath);
+            const absolutePathResult = requireAbsoluteFilesystemPath(codebasePath, "path");
+            if (!absolutePathResult.ok) {
+                return this.host.manageResponse("repair", codebasePath, "error", absolutePathResult.message);
+            }
+            absolutePath = absolutePathResult.absolutePath;
             if (!fs.existsSync(absolutePath)) {
                 return this.host.manageResponse("repair", absolutePath, "error", `Error: Path '${absolutePath}' does not exist. Original input: '${codebasePath}'`);
             }
@@ -491,16 +503,25 @@ export class ManageIndexingHandlers {
             catch (pruneError) {
                 console.warn(`[BACKGROUND-INDEX] Failed to retire superseded generations for '${absolutePath}': ${formatUnknownError(pruneError)}`);
             }
+            // indexStatus is carried on stats (completed | limit_reached). limit_reached remains
+            // searchable only when core wrote a completion marker for partial vector proof;
+            // navigation still fails closed via indexStatus checks (partial_index_navigation_unavailable).
             this.host.snapshotManager.setCodebaseIndexed(absolutePath, stats, this.host.runtimeFingerprint, "verified", targetCollectionName);
             this.host.snapshotManager.setCodebaseIndexManifest(absolutePath, this.host.getContextTrackedRelativePaths(absolutePath));
             this.host.setIndexingStats({ indexedFiles: stats.indexedFiles, totalChunks: stats.totalChunks });
             await this.host.syncManager.recordCurrentIgnoreControlSignature(absolutePath);
             this.host.saveSnapshotIfSupported();
-            await this.host.rebuildCallGraphForIndex(absolutePath);
+            // Full navigation rebuild only for completed indexes; partial indexes have no registry seal.
+            if (stats.status === "completed") {
+                await this.host.rebuildCallGraphForIndex(absolutePath);
+            }
             await this.host.touchWatchedCodebase(absolutePath);
             let message = `Background indexing completed for '${absolutePath}'.\nIndexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks.`;
             if (stats.status === "limit_reached") {
-                message += "\n⚠️  Warning: Indexing stopped because the chunk limit (450,000) was reached. The index may be incomplete.";
+                message += "\n⚠️  Warning: Indexing stopped because the chunk limit (450,000) was reached."
+                    + " Search may return incomplete results with SEARCH_PARTIAL_INDEX warnings."
+                    + " file_outline/call_graph are unavailable until a full reindex completes successfully."
+                    + " This is not a fully complete index.";
             }
             console.log(`[BACKGROUND-INDEX] ${message}`);
         }

package/dist/core/manage-maintenance-handlers.d.ts

@@ -3,6 +3,8 @@ import type { SnapshotCorruptionWarning, SnapshotManager } from "./snapshot.js";
 import type { SyncManager } from "./sync.js";
 import type { TrackedRootReadiness } from "./tracked-root-readiness.js";
 import { type VectorBackendDiagnostic } from "./backend-diagnostics.js";
+import type { ManageIndexAction, ManageIndexStatus } from "./manage-types.js";
+import { type RuntimeOwnerMutationAction, type RuntimeOwnersSummary } from "./runtime-owner.js";
 type ToolArgs = Record<string, unknown>;
 type ToolTextResponse = {
     content: Array<{
@@ -11,7 +13,6 @@ type ToolTextResponse = {
     }>;
     isError?: boolean;
 };
-type ManageIndexStatus = "ok" | "error" | "not_ready" | "not_indexed" | "blocked" | "requires_reindex";
 type ManageMaintenanceHandlersHost = {
     context: Pick<Context, "clearIndex">;
     snapshotManager: Pick<SnapshotManager, "removeCodebaseCompletely">;
@@ -23,11 +24,11 @@ type ManageMaintenanceHandlersHost = {
     getSnapshotCodebaseStatus(codebasePath: string): string;
     getSnapshotCodebaseInfo(codebasePath: string): Record<string, unknown> | undefined;
     getSnapshotCorruptionWarning(): SnapshotCorruptionWarning | undefined;
-    buildRuntimeOwnerConflictResponseIfBlocked(action: "clear" | "sync", codebasePath: string): Promise<ToolTextResponse | null>;
+    buildRuntimeOwnerConflictResponseIfBlocked(action: Extract<RuntimeOwnerMutationAction, "clear" | "sync">, codebasePath: string): Promise<ToolTextResponse | null>;
     recoverStaleIndexingStateIfNeeded(codebasePath: string): Promise<void>;
-    manageResponse(action: string, path: string, status: ManageIndexStatus | string, message: string, options?: Record<string, unknown>): ToolTextResponse;
+    manageResponse(action: ManageIndexAction | string, path: string, status: ManageIndexStatus | string, message: string, options?: Record<string, unknown>): ToolTextResponse;
     buildCreateHint(codebasePath: string): Record<string, unknown>;
-    buildManageActionBlockedMessage(codebasePath: string, action: "clear" | "sync"): string;
+    buildManageActionBlockedMessage(codebasePath: string, action: Extract<RuntimeOwnerMutationAction, "clear" | "sync">): string;
     buildStatusHint(codebasePath: string): Record<string, unknown>;
     getManageRetryAfterMs(): number;
     buildIndexingMetadata(codebasePath: string): Record<string, unknown> | undefined;
@@ -51,6 +52,8 @@ type ManageMaintenanceHandlersHost = {
     buildReindexHint(codebasePath: string): Record<string, unknown>;
     touchWatchedCodebase(codebasePath: string): Promise<void>;
     manageVectorBackendResponse(action: string, path: string, diagnostic: VectorBackendDiagnostic, humanText?: string): ToolTextResponse;
+    /** Optional live MCP runtime owner summary for status diagnostics. */
+    getLiveOwnersSummary?(): Promise<RuntimeOwnersSummary | null> | RuntimeOwnersSummary | null;
 };
 export declare class ManageMaintenanceHandlers {
     private readonly host;

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

@@ -1,8 +1,9 @@
 import * as fs from "fs";
-import { COLLECTION_LIMIT_MESSAGE, RemoteCollectionDeletePendingError, } from "@zokizuan/satori-core";
+import { COLLECTION_LIMIT_MESSAGE, RemoteCollectionDeletePendingError, formatSymbolQualityMarker, resolveSymbolQualitySummary, } from "@zokizuan/satori-core";
 import { WARNING_CODES } from "./warnings.js";
 import { classifyVectorBackendError, } from "./backend-diagnostics.js";
-import { ensureAbsolutePath } from "../utils.js";
+import { requireAbsoluteFilesystemPath } from "../utils.js";
+import { formatRuntimeOwnersStatusLine, } from "./runtime-owner.js";
 function collectErrorFragments(value, output, visited, depth = 0) {
     if (value === null || value === undefined || depth > 4 || output.length >= 8) {
         return;
@@ -78,7 +79,11 @@ export class ManageMaintenanceHandlers {
     }
     async handleClearIndex(args) {
         const codebasePath = typeof args.path === "string" ? args.path : "";
-        const requestedPath = ensureAbsolutePath(codebasePath);
+        const absolutePathResult = requireAbsoluteFilesystemPath(codebasePath, "path");
+        if (!absolutePathResult.ok) {
+            return this.host.manageResponse("clear", codebasePath, "error", absolutePathResult.message);
+        }
+        const requestedPath = absolutePathResult.absolutePath;
         if (this.host.getSnapshotAllCodebases().length === 0) {
             return this.host.manageResponse("clear", requestedPath, "not_indexed", "No codebases are currently tracked.", { reason: "not_indexed" });
         }
@@ -167,7 +172,11 @@ export class ManageMaintenanceHandlers {
     }
     async handleGetIndexingStatus(args) {
         const codebasePath = typeof args.path === "string" ? args.path : "";
-        const requestedPath = ensureAbsolutePath(codebasePath);
+        const absolutePathResult = requireAbsoluteFilesystemPath(codebasePath, "path");
+        if (!absolutePathResult.ok) {
+            return this.host.manageResponse("status", codebasePath, "error", absolutePathResult.message);
+        }
+        const requestedPath = absolutePathResult.absolutePath;
         try {
             const absolutePath = requestedPath;
             if (!fs.existsSync(absolutePath)) {
@@ -281,7 +290,16 @@ export class ManageMaintenanceHandlers {
                 const info = trackedRootState.root.info || this.host.getSnapshotCodebaseInfo(trackedRootState.root.path);
                 switch (status) {
                     case "indexed":
-                        if (info?.status === "indexed") {
+                        if (info?.status === "indexed" && info.indexStatus === "limit_reached") {
+                            statusMessage = `⚠️ Codebase '${trackedRootState.root.path}' is partially indexed (limit_reached).`;
+                            statusMessage += `\n📊 Statistics: ${info.indexedFiles} files, ${info.totalChunks} chunks`;
+                            statusMessage += `\n📅 Status: ${info.indexStatus}`;
+                            statusMessage += `\nSearch may return incomplete results; file_outline/call_graph are unavailable until a full reindex completes.`;
+                            if (typeof info.lastUpdated === "string") {
+                                statusMessage += `\n🕐 Last updated: ${new Date(info.lastUpdated).toLocaleString()}`;
+                            }
+                        }
+                        else if (info?.status === "indexed") {
                             statusMessage = `✅ Codebase '${trackedRootState.root.path}' is fully indexed and ready for search.`;
                             statusMessage += `\n📊 Statistics: ${info.indexedFiles} files, ${info.totalChunks} chunks`;
                             statusMessage += `\n📅 Status: ${info.indexStatus}`;
@@ -319,6 +337,17 @@ export class ManageMaintenanceHandlers {
                 statusMessage += `\n⚠️ Completion proof check is temporarily unavailable (probe_failed); keeping local status.`;
                 warnings.push(WARNING_CODES.IGNORE_POLICY_PROBE_FAILED);
             }
+            // F9: observed symbol quality from registry (not parser-cause diagnosis).
+            let symbolQuality;
+            // Attach observed quality for lifecycle statuses that refer to a real root path.
+            if (envelopeStatus === "ok" || envelopeStatus === "not_ready" || envelopeStatus === "not_indexed") {
+                symbolQuality = await resolveSymbolQualitySummary({
+                    normalizedRootPath: envelopePath,
+                });
+                if (envelopeStatus === "ok") {
+                    statusMessage += `\n🧭 ${formatSymbolQualityMarker(symbolQuality)}: ${symbolQuality.message}`;
+                }
+            }
             const pathInfo = codebasePath !== envelopePath
                 ? `\nNote: Input path '${codebasePath}' was resolved to absolute path '${envelopePath}'`
                 : "";
@@ -335,10 +364,27 @@ export class ManageMaintenanceHandlers {
                     snapshotCorruption: snapshotCorruptionWarning,
                 };
             }
-            return this.host.manageResponse("status", envelopePath, envelopeStatus, statusMessage + compatibilityStatus + pathInfo + snapshotWarningText, {
+            let runtimeOwnersLine = "";
+            if (typeof this.host.getLiveOwnersSummary === "function") {
+                try {
+                    const ownersSummary = await this.host.getLiveOwnersSummary();
+                    if (ownersSummary) {
+                        runtimeOwnersLine = `\n👥 ${formatRuntimeOwnersStatusLine(ownersSummary)}`;
+                        envelopeHints = {
+                            ...(envelopeHints || {}),
+                            runtimeOwners: ownersSummary,
+                        };
+                    }
+                }
+                catch {
+                    // Diagnostic only; never fail status on owner registry issues.
+                }
+            }
+            return this.host.manageResponse("status", envelopePath, envelopeStatus, statusMessage + compatibilityStatus + pathInfo + snapshotWarningText + runtimeOwnersLine, {
                 reason: envelopeReason,
                 hints: envelopeHints,
                 warnings,
+                ...(symbolQuality ? { symbolQuality } : {}),
             });
         }
         catch (error) {
@@ -347,7 +393,11 @@ export class ManageMaintenanceHandlers {
     }
     async handleSyncCodebase(args) {
         const codebasePath = typeof args.path === "string" ? args.path : "";
-        const requestedPath = ensureAbsolutePath(codebasePath);
+        const absolutePathResult = requireAbsoluteFilesystemPath(codebasePath, "path");
+        if (!absolutePathResult.ok) {
+            return this.host.manageResponse("sync", codebasePath, "error", absolutePathResult.message);
+        }
+        const requestedPath = absolutePathResult.absolutePath;
         try {
             const absolutePath = requestedPath;
             if (!fs.existsSync(absolutePath)) {

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

@@ -1,5 +1,8 @@
+import type { SymbolQualitySummary } from "@zokizuan/satori-core";
 import { WarningCode } from "./warnings.js";
-export type ManageIndexAction = "create" | "reindex" | "sync" | "status" | "clear" | "repair";
+/** Public manage_index action set (SSOT for schema, docs, and contract tests). */
+export declare const MANAGE_INDEX_ACTIONS: readonly ["create", "reindex", "sync", "status", "clear", "repair"];
+export type ManageIndexAction = (typeof MANAGE_INDEX_ACTIONS)[number];
 export type ManageIndexStatus = "ok" | "not_ready" | "not_indexed" | "requires_reindex" | "blocked" | "error";
 export type ManageIndexReason = "indexing" | "not_indexed" | "requires_reindex" | "unnecessary_reindex_ignore_only" | "preflight_unknown" | "backend_timeout" | "remote_delete_pending" | "missing_provider_config" | "vector_backend_unavailable" | "runtime_owner_conflict" | "needs_create";
 export type VectorBackendResponseCode = "ZILLIZ_CLUSTER_STOPPED" | "VECTOR_BACKEND_AUTH_FAILED" | "VECTOR_BACKEND_UNREACHABLE" | "VECTOR_BACKEND_TIMEOUT" | "VECTOR_BACKEND_CONNECTION_CLOSED";
@@ -25,5 +28,7 @@ export interface ManageIndexResponseEnvelope {
         confidence: "high" | "low";
         probeFailed?: boolean;
     };
+    /** Observed symbol quality from registry (F9); not parser-cause diagnosis. */
+    symbolQuality?: SymbolQualitySummary;
 }
 //# sourceMappingURL=manage-types.d.ts.map

package/dist/core/manage-types.js

@@ -1,2 +1,10 @@
-export {};
+/** Public manage_index action set (SSOT for schema, docs, and contract tests). */
+export const MANAGE_INDEX_ACTIONS = [
+    "create",
+    "reindex",
+    "sync",
+    "status",
+    "clear",
+    "repair",
+];
 //# sourceMappingURL=manage-types.js.map

package/dist/core/navigation-handlers.d.ts

@@ -1,4 +1,9 @@
 import { type NavigationStore, type SymbolRecord } from "@zokizuan/satori-core";
+/**
+ * Non-blocking outline warning: count + optional sample keys + agent action.
+ * Does not dump every registry diagnostic string into the outline payload.
+ */
+export declare function formatOutlineSymbolRegistryWarnings(registryWarnings: readonly string[]): string | undefined;
 import { type PythonSourceBackedSpanRepair } from "./python-call-fallback.js";
 import type { CompletionProbeDebugHint, TrackedRootReadiness } from "./tracked-root-readiness.js";
 import type { CallGraphDirection, CallGraphEdge, CallGraphNode, CallGraphNote, CallGraphSymbolRef, CallGraphTestReference } from "./call-graph.js";
@@ -126,6 +131,7 @@ type NavigationHandlersHost = {
             nodeCount: number;
             edgeCount: number;
         };
+        hints?: Record<string, unknown>;
     } | null>;
 };
 export declare class NavigationHandlers {

package/dist/core/navigation-handlers.js

@@ -1,9 +1,29 @@
 import * as fs from "fs";
 import * as path from "path";
-import { getSupportedExtensionsForCapability, } from "@zokizuan/satori-core";
+import { compareContractStrings, getSupportedExtensionsForCapability, } from "@zokizuan/satori-core";
+const OUTLINE_DUPLICATE_SYMBOL_KEY_RE = /^Duplicate symbolKey '([^']+)' has \d+ candidates$/;
+/**
+ * Non-blocking outline warning: count + optional sample keys + agent action.
+ * Does not dump every registry diagnostic string into the outline payload.
+ */
+export function formatOutlineSymbolRegistryWarnings(registryWarnings) {
+    if (registryWarnings.length === 0) {
+        return undefined;
+    }
+    const samples = [];
+    for (const warning of registryWarnings) {
+        const match = OUTLINE_DUPLICATE_SYMBOL_KEY_RE.exec(warning);
+        if (match) {
+            samples.push(match[1]);
+        }
+    }
+    samples.sort(compareContractStrings);
+    const sample = samples.slice(0, 3).join(",");
+    return `OUTLINE_SYMBOL_REGISTRY_WARNINGS:${registryWarnings.length} action=treat_outline_as_degraded_identity${sample ? ` sample=${sample}` : ""}`;
+}
 import { repairSourceBackedPythonSpan, } from "./python-call-fallback.js";
 import { buildRegistryFileOutlinePayload, findExactRegistrySymbols, } from "./registry-file-outline.js";
-import { ensureAbsolutePath, trackCodebasePath } from "../utils.js";
+import { requireAbsoluteFilesystemPath, requireRepoRelativeFilePath, trackCodebasePath } from "../utils.js";
 const OUTLINE_SUPPORTED_EXTENSIONS = getSupportedExtensionsForCapability("fileOutline");
 const PARTIAL_INDEX_NAVIGATION_UNAVAILABLE_DETAIL = "Partial index/search data may exist, but navigation sidecars were not published because indexing stopped before completion.";
 function collectErrorFragments(value, output, visited, depth = 0) {
@@ -81,8 +101,24 @@ export class NavigationHandlers {
         const symbolIdExact = typeof args?.symbolIdExact === "string" ? args.symbolIdExact.trim() : undefined;
         const symbolLabelExact = typeof args?.symbolLabelExact === "string" ? args.symbolLabelExact.trim() : undefined;
         try {
-            const absoluteRoot = ensureAbsolutePath(args.path);
-            const normalizedFile = this.host.normalizeRelativeFilePath(args.file);
+            const absoluteRootResult = requireAbsoluteFilesystemPath(args.path, "path");
+            if (!absoluteRootResult.ok) {
+                const payload = this.host.buildInvalidFileOutlineRequestPayload(absoluteRootResult.path, typeof args.file === "string" ? args.file : "", absoluteRootResult.message, "not_indexed", "not_indexed");
+                return {
+                    content: [{ type: "text", text: this.host.stringifyToolJson(payload) }],
+                    isError: true,
+                };
+            }
+            const absoluteRoot = absoluteRootResult.absolutePath;
+            const relativeFileResult = requireRepoRelativeFilePath(typeof args.file === "string" ? args.file : "", "file");
+            if (!relativeFileResult.ok) {
+                const payload = this.host.buildInvalidFileOutlineRequestPayload(absoluteRoot, relativeFileResult.path, relativeFileResult.message, "not_found");
+                return {
+                    content: [{ type: "text", text: this.host.stringifyToolJson(payload) }],
+                    isError: true,
+                };
+            }
+            const normalizedFile = this.host.normalizeRelativeFilePath(relativeFileResult.relativePath);
             if (!fs.existsSync(absoluteRoot)) {
                 const payload = this.host.buildInvalidFileOutlineRequestPayload(absoluteRoot, normalizedFile, `Path '${absoluteRoot}' does not exist. file_outline requires an indexed codebase directory root.`, "not_indexed", "not_indexed");
                 return {
@@ -227,9 +263,11 @@ export class NavigationHandlers {
                         codebaseRoot: effectiveRoot,
                         registryManifestHash: registryState.manifestHash,
                     });
-                    const outlineWarnings = registryState.warnings.length > 0
-                        ? [`OUTLINE_SYMBOL_REGISTRY_WARNINGS:${registryState.warnings.length}`]
-                        : [];
+                    const outlineWarnings = [];
+                    const registryWarning = formatOutlineSymbolRegistryWarnings(registryState.warnings);
+                    if (registryWarning) {
+                        outlineWarnings.push(registryWarning);
+                    }
                     if (relationshipGraph.warning) {
                         outlineWarnings.push(`OUTLINE_${relationshipGraph.warning}`);
                     }
@@ -307,7 +345,11 @@ export class NavigationHandlers {
             };
         }
         catch (error) {
-            const payload = this.host.buildInvalidFileOutlineRequestPayload(typeof args?.path === "string" ? ensureAbsolutePath(args.path) : "", typeof args?.file === "string" ? this.host.normalizeRelativeFilePath(args.file) : "", `Unexpected file_outline failure: ${formatUnknownError(error)}`, "not_ready");
+            const pathResult = typeof args?.path === "string"
+                ? requireAbsoluteFilesystemPath(args.path)
+                : null;
+            const pathForError = pathResult?.ok ? pathResult.absolutePath : (typeof args?.path === "string" ? args.path : "");
+            const payload = this.host.buildInvalidFileOutlineRequestPayload(pathForError, typeof args?.file === "string" ? this.host.normalizeRelativeFilePath(args.file) : "", `Unexpected file_outline failure: ${formatUnknownError(error)}`, "not_ready");
             return {
                 content: [{ type: "text", text: this.host.stringifyToolJson(payload) }],
                 isError: true,
@@ -322,19 +364,41 @@ export class NavigationHandlers {
         const depth = Number.isFinite(args?.depth) ? Math.max(1, Math.min(3, Number(args.depth))) : 1;
         const limit = Number.isFinite(args?.limit) ? Math.max(1, Number(args.limit)) : 20;
         const symbolRef = args?.symbolRef;
+        const symbolFileResult = typeof symbolRef?.file === "string"
+            ? requireRepoRelativeFilePath(symbolRef.file, "symbolRef.file")
+            : { ok: false, path: "", message: "symbolRef.file is required." };
         const normalizedSymbolRef = {
-            file: typeof symbolRef?.file === "string" ? this.host.normalizeRelativeFilePath(symbolRef.file) : "",
+            file: symbolFileResult.ok
+                ? this.host.normalizeRelativeFilePath(symbolFileResult.relativePath)
+                : (typeof symbolRef?.file === "string" ? this.host.normalizeRelativeFilePath(symbolRef.file) : ""),
             symbolId: typeof symbolRef?.symbolId === "string" ? symbolRef.symbolId : "",
             ...(typeof symbolRef?.symbolLabel === "string" ? { symbolLabel: symbolRef.symbolLabel } : {}),
             ...(symbolRef?.span ? { span: symbolRef.span } : {}),
         };
+        const absolutePathResult = typeof args?.path === "string"
+            ? requireAbsoluteFilesystemPath(args.path, "path")
+            : { ok: false, path: "", message: "path is required." };
         const invalidSymbolRefContext = {
-            path: typeof args?.path === "string" ? ensureAbsolutePath(args.path) : "",
+            path: absolutePathResult.ok ? absolutePathResult.absolutePath : (typeof args?.path === "string" ? args.path : ""),
             symbolRef: normalizedSymbolRef,
             direction,
             depth,
             limit,
         };
+        if (!absolutePathResult.ok) {
+            const payload = this.host.buildInvalidCallGraphRequestPayload(invalidSymbolRefContext, absolutePathResult.message, "not_indexed", "not_indexed");
+            return {
+                content: [{ type: "text", text: this.host.stringifyToolJson(payload) }],
+                isError: true,
+            };
+        }
+        if (!symbolFileResult.ok) {
+            const payload = this.host.buildInvalidCallGraphRequestPayload(invalidSymbolRefContext, symbolFileResult.message, "not_found", "invalid_symbol_ref");
+            return {
+                content: [{ type: "text", text: this.host.stringifyToolJson(payload) }],
+                isError: true,
+            };
+        }
         if (!symbolRef || typeof symbolRef.file !== "string" || typeof symbolRef.symbolId !== "string") {
             const payload = this.host.buildInvalidCallGraphRequestPayload(invalidSymbolRefContext, "symbolRef with { file, symbolId } is required.", "not_found", "invalid_symbol_ref");
             return {
@@ -343,7 +407,7 @@ export class NavigationHandlers {
             };
         }
         try {
-            const absolutePath = ensureAbsolutePath(typeof args.path === "string" ? args.path : "");
+            const absolutePath = absolutePathResult.absolutePath;
             if (!fs.existsSync(absolutePath)) {
                 const payload = this.host.buildInvalidCallGraphRequestPayload({
                     path: absolutePath,
@@ -658,8 +722,11 @@ export class NavigationHandlers {
             };
         }
         catch (error) {
+            const pathResult = typeof args?.path === "string"
+                ? requireAbsoluteFilesystemPath(args.path)
+                : null;
             const payload = this.host.buildInvalidCallGraphRequestPayload({
-                path: typeof args?.path === "string" ? ensureAbsolutePath(args.path) : "",
+                path: pathResult?.ok ? pathResult.absolutePath : (typeof args?.path === "string" ? args.path : ""),
                 symbolRef: normalizedSymbolRef,
                 direction,
                 depth,

package/dist/core/registry-file-outline.d.ts

@@ -1,4 +1,4 @@
-import type { SymbolRecord } from "@zokizuan/satori-core";
+import { type SymbolRecord } from "@zokizuan/satori-core";
 import type { CallGraphHint } from "./search-types.js";
 import type { FileOutlineResponseEnvelope } from "./search-types.js";
 import { type PythonSourceBackedSpanRepair } from "./python-call-fallback.js";

package/dist/core/registry-file-outline.js

@@ -1,3 +1,4 @@
+import { compareContractStrings } from "@zokizuan/satori-core";
 import { repairSourceBackedPythonSpans, } from "./python-call-fallback.js";
 function compareNullableNumbersAsc(a, b) {
     const left = a ?? Number.POSITIVE_INFINITY;
@@ -7,7 +8,7 @@ function compareNullableNumbersAsc(a, b) {
 function compareNullableStringsAsc(a, b) {
     const left = a ?? "\uffff";
     const right = b ?? "\uffff";
-    return left.localeCompare(right);
+    return compareContractStrings(left, right);
 }
 function sortFileOutlineSymbols(symbols) {
     return [...symbols].sort((a, b) => {
@@ -106,7 +107,7 @@ export function buildRegistryFileOutlinePayload(input) {
         if (!visibleState.hasExtractedSymbols && symbols.length > 0) {
             warningSet.add("OUTLINE_SYNTHESIZED_FILE_SYMBOL");
         }
-        return [...warningSet].sort((a, b) => a.localeCompare(b));
+        return [...warningSet].sort(compareContractStrings);
     };
     if (input.resolveMode === "exact") {
         const exactMatchIds = new Set(findExactRegistrySymbols({

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

@@ -2,6 +2,11 @@ import { type NavigationStore, type SymbolRecord, type SymbolRegistry } from "@z
 import type { SnapshotManager } from "./snapshot.js";
 import type { CallGraphDirection, CallGraphEdge, CallGraphNode, CallGraphNote, CallGraphSidecarManager, CallGraphTestReference } from "./call-graph.js";
 import { type PythonSourceBackedSpanRepair } from "./python-call-fallback.js";
+/**
+ * Collapse per-key registry duplicate warnings into one count + sample line.
+ * Presentation-only: registry build still retains full diagnostics.
+ */
+export declare function collapseRegistryDuplicateKeyWarnings(warnings: readonly string[]): string[];
 type RelationshipBackedCallGraphHost = {
     navigationStore: NavigationStore;
     callGraphManager: CallGraphSidecarManager;
@@ -37,7 +42,20 @@ type RelationshipBackedCallGraphResult = {
         nodeCount: number;
         edgeCount: number;
     };
+    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.
+ * Never use the callee defining file when sites disagree or are multi-file.
+ */
+export declare function uniqueInboundCallerSiteFile(notes: readonly CallGraphNote[]): string | undefined;
+/**
+ * Production suppressed callers first; collapse excess test/fixture caller notes into one summary.
+ */
+export declare function prioritizeInboundSuppressedNotes(notes: readonly CallGraphNote[]): CallGraphNote[];
 export declare class RelationshipBackedCallGraph {
     private readonly host;
     constructor(host: RelationshipBackedCallGraphHost);