@zokizuan/satori-mcp 4.11.8 → 4.11.13

package/README.md

@@ -7,8 +7,8 @@ Read-only MCP server for Satori. It gives coding agents six deterministic tools
 Use the CLI installer for normal setup:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.6 install --client all
-npx -y @zokizuan/satori-cli@0.4.6 doctor
+npx -y @zokizuan/satori-cli@latest install --client all
+npx -y @zokizuan/satori-cli@latest doctor
 ```
 
 The CLI installer supports `codex`, `claude`, `opencode`, and `all`. It creates the runtime cache, writes the stable launcher, and writes client config for you. Avoid using `npx` as the resident MCP server command; first-run package resolution can exceed normal MCP startup timeouts.
@@ -16,7 +16,7 @@ The CLI installer supports `codex`, `claude`, `opencode`, and `all`. It creates
 Use `--profile default|minimal|all-text` to write repo-local `satori.toml` during install:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.6 install --client all --profile minimal
+npx -y @zokizuan/satori-cli@latest install --client all --profile minimal
 ```
 
 Profiles control indexing breadth, not search scope. `default` is safe-broad, `minimal` indexes source plus docs/text, and `all-text` indexes additional UTF-8 text files under the size limit. `search_codebase` still defaults to `scope=runtime`.
@@ -45,7 +45,7 @@ For Codex, add `--install-guidance-hook` only when you want an installer-managed
 Advanced direct execution is available through the package bin:
 
 ```bash
-npx -y @zokizuan/satori-mcp@4.11.8 --help
+npx -y @zokizuan/satori-mcp@4.11.13 --help
 ```
 
 Use direct package execution for inspection, smoke tests, or unsupported harnesses. For supported clients, prefer `satori-cli install` so startup does not depend on package-manager resolution.
@@ -131,11 +131,11 @@ The full generated tool reference below is kept in the npm README for MCP client
 
 ### `manage_index`
 
-Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action="status" to observe progress.
+Manage index lifecycle operations (create/reindex/sync/status/clear/repair) for a codebase path. repair rebuilds local readiness only when existing vector payload and trusted runtime fingerprint proof match; otherwise it refuses and asks for create/reindex. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action="status" to observe progress.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `action` | enum("create", "reindex", "sync", "status", "clear") | yes |  | Required operation to run. |
+| `action` | enum("create", "reindex", "sync", "status", "clear", "repair") | yes |  | Required operation to run. |
 | `path` | string | yes |  | ABSOLUTE path to the target codebase. |
 | `force` | boolean | no |  | Only for action='create'. Force rebuild from scratch. |
 | `allowUnnecessaryReindex` | boolean | no |  | Only for action='reindex'. Override preflight block when reindex is detected as unnecessary ignore-only churn. |

package/dist/config.d.ts

@@ -54,6 +54,7 @@ export interface CodebaseSnapshotV1 {
 }
 interface CodebaseInfoBase {
     lastUpdated: string;
+    collectionName?: string;
     indexFingerprint?: IndexFingerprint;
     fingerprintSource?: FingerprintSource;
     reindexReason?: 'legacy_unverified_fingerprint' | 'fingerprint_mismatch' | 'missing_fingerprint' | 'navigation_recovery_failed';

package/dist/config.js

@@ -209,7 +209,7 @@ Environment Variables:
 
 Examples:
   # Install resident MCP config without package-manager startup on every client launch
-  npx -y @zokizuan/satori-cli@0.4.6 install --client all
+  npx -y @zokizuan/satori-cli@latest install --client all
 
   # Start MCP server with OpenAI and explicit Milvus address
   OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 satori

package/dist/core/backend-diagnostics.js

@@ -36,7 +36,7 @@ function createVectorBackendDiagnostic(code) {
         case "ZILLIZ_CLUSTER_STOPPED":
             return {
                 code,
-                message: "Vector backend is unavailable because the Zilliz Cloud cluster is stopped.",
+                message: "Zilliz Cloud cluster is stopped. Resume it in Zilliz Cloud, then retry the tool call.",
                 hints: {
                     backend: {
                         code,
@@ -101,13 +101,16 @@ function createVectorBackendDiagnostic(code) {
         case "VECTOR_BACKEND_CONNECTION_CLOSED":
             return {
                 code,
-                message: "Vector backend connection closed before the tool call completed.",
+                message: "Vector backend connection closed before the tool call completed. Check backend health, provider environment, network connectivity, or an MCP process restart in the previous log lines.",
                 hints: {
                     backend: {
                         code,
                         provider: "unknown",
                         retryable: true,
                         nextSteps: [
+                            "If the previous response mentions ZILLIZ_CLUSTER_STOPPED, resume the Zilliz cluster at https://cloud.zilliz.com.",
+                            "If the previous response mentions MISSING_PROVIDER_CONFIG, set the missing env values in the MCP client environment and restart the client.",
+                            "For non-Zilliz Milvus-compatible backends, confirm the service is running and reachable at MILVUS_ADDRESS.",
                             "Retry the MCP tool call after confirming the backend is healthy.",
                             "Restart the MCP client/session if the MCP process exited after the transport failure.",
                         ],

package/dist/core/handlers.d.ts

@@ -58,6 +58,8 @@ export declare class ToolHandlers {
     private buildReindexInstruction;
     private buildReindexHint;
     private buildCreateHint;
+    private buildSyncHint;
+    private buildRepairHint;
     private buildManageIndexRecommendedAction;
     private buildStatusHint;
     private buildManageRequiresReindexHints;
@@ -83,9 +85,9 @@ export declare class ToolHandlers {
     private getContextActiveIgnorePatterns;
     private getContextIndexedExtensions;
     private getContextTrackedRelativePaths;
-    private writeIndexCompletionMarker;
     private clearIndexCompletionMarker;
     private pruneIndexedCollectionFamily;
+    private pruneUnprovenStagedCollectionFamily;
     private markCodebaseCleared;
     private stringifyToolJson;
     private buildRuntimeOwnerConflictResponseIfBlocked;
@@ -96,11 +98,14 @@ export declare class ToolHandlers {
     private buildManageActionBlockedMessage;
     private getManageRetryAfterMs;
     private buildStaleLocalHint;
+    private getSnapshotCollectionName;
+    private canSyncStaleLocal;
     private buildStaleLocalMessage;
     private withProofDebugHint;
     private validateCompletionProof;
     private extractIndexedRecoveryFromCompletionProof;
     private recoverIndexedSnapshotFromCompletionProof;
+    private getActiveIndexedCollectionNameForSnapshotRecovery;
     private refreshSnapshotStateFromDisk;
     private isPathWithinCodebase;
     private getTrackedRootEntryForPath;
@@ -181,6 +186,13 @@ export declare class ToolHandlers {
         }>;
         isError?: boolean;
     }>;
+    handleRepairIndex(args: ToolArgs): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
     handleSearchCode(args: ToolArgs): Promise<{
         content: {
             type: string;

package/dist/core/handlers.js

@@ -151,6 +151,7 @@ export class ToolHandlers {
             buildManageIndexRecommendedAction: this.buildManageIndexRecommendedAction.bind(this),
             buildCreateHint: this.buildCreateHint.bind(this),
             buildReindexHint: this.buildReindexHint.bind(this),
+            buildRepairHint: this.buildRepairHint.bind(this),
             buildStatusHint: this.buildStatusHint.bind(this),
             buildStaleLocalHint: this.buildStaleLocalHint.bind(this),
             buildStaleLocalMessage: this.buildStaleLocalMessage.bind(this),
@@ -267,8 +268,10 @@ export class ToolHandlers {
             buildStaleLocalMessage: this.buildStaleLocalMessage.bind(this),
             enforceFingerprintGate: this.enforceFingerprintGate.bind(this),
             buildReindexHint: this.buildReindexHint.bind(this),
+            buildSyncHint: this.buildSyncHint.bind(this),
             touchWatchedCodebase: this.touchWatchedCodebase.bind(this),
             manageVectorBackendResponse: this.toolResponseBuilders.manageVectorBackendResponse.bind(this.toolResponseBuilders),
+            canSyncStaleLocal: this.canSyncStaleLocal.bind(this),
         };
         this.manageMaintenanceHandlers = new ManageMaintenanceHandlers(manageMaintenanceHandlersHost);
         const getManageIndexingContext = () => this.context;
@@ -299,6 +302,7 @@ export class ToolHandlers {
             getSnapshotCodebaseInfo: this.getSnapshotCodebaseInfo.bind(this),
             getSnapshotIndexedCodebases: this.getSnapshotIndexedCodebases.bind(this),
             buildManageActionBlockedMessage: this.buildManageActionBlockedMessage.bind(this),
+            buildCreateHint: this.buildCreateHint.bind(this),
             buildStatusHint: this.buildStatusHint.bind(this),
             getManageRetryAfterMs: this.getManageRetryAfterMs.bind(this),
             buildIndexingMetadata: this.buildIndexingMetadata.bind(this),
@@ -319,8 +323,8 @@ export class ToolHandlers {
             getContextActiveIgnorePatterns: this.getContextActiveIgnorePatterns.bind(this),
             getContextIndexedExtensions: this.getContextIndexedExtensions.bind(this),
             canonicalizeCodebasePath: this.canonicalizeCodebasePath.bind(this),
-            writeIndexCompletionMarker: this.writeIndexCompletionMarker.bind(this),
             pruneIndexedCollectionFamily: this.pruneIndexedCollectionFamily.bind(this),
+            pruneUnprovenStagedCollectionFamily: this.pruneUnprovenStagedCollectionFamily.bind(this),
             getContextTrackedRelativePaths: this.getContextTrackedRelativePaths.bind(this),
             setIndexingStats: this.setIndexingStats.bind(this),
             rebuildCallGraphForIndex: this.rebuildCallGraphForIndex.bind(this),
@@ -396,6 +400,24 @@ export class ToolHandlers {
             }
         };
     }
+    buildSyncHint(codebasePath) {
+        return {
+            tool: "manage_index",
+            args: {
+                action: "sync",
+                path: codebasePath
+            }
+        };
+    }
+    buildRepairHint(codebasePath) {
+        return {
+            tool: "manage_index",
+            args: {
+                action: "repair",
+                path: codebasePath
+            }
+        };
+    }
     buildManageIndexRecommendedAction(action, codebasePath, reason) {
         return {
             tool: "manage_index",
@@ -567,9 +589,6 @@ export class ToolHandlers {
         const paths = this.contextLifecycle().getTrackedRelativePaths?.(codebasePath);
         return Array.isArray(paths) ? paths.filter((entry) => typeof entry === 'string') : [];
     }
-    async writeIndexCompletionMarker(codebasePath, marker) {
-        await this.contextLifecycle().writeIndexCompletionMarker?.(codebasePath, marker);
-    }
     async clearIndexCompletionMarker(codebasePath) {
         await this.contextLifecycle().clearIndexCompletionMarker?.(codebasePath);
     }
@@ -577,6 +596,10 @@ export class ToolHandlers {
         const dropped = await this.contextLifecycle().pruneIndexedCollectionFamily?.(codebasePath, keepCollectionName);
         return Array.isArray(dropped) ? dropped.filter((entry) => typeof entry === 'string') : [];
     }
+    async pruneUnprovenStagedCollectionFamily(codebasePath) {
+        const dropped = await this.contextLifecycle().pruneUnprovenStagedCollectionFamily?.(codebasePath);
+        return Array.isArray(dropped) ? dropped.filter((entry) => typeof entry === 'string') : [];
+    }
     markCodebaseCleared(codebasePath, collectionName) {
         this.snapshotCapabilities().markCodebaseCleared?.(codebasePath, collectionName);
     }
@@ -654,7 +677,8 @@ export class ToolHandlers {
         }
         const decision = decideInterruptedIndexingRecovery(marker, this.runtimeFingerprint);
         if (decision.action === "promote_indexed") {
-            this.snapshotManager.setCodebaseIndexed(codebasePath, decision.stats, decision.indexFingerprint, "verified");
+            const collectionName = await this.getActiveIndexedCollectionNameForSnapshotRecovery(codebasePath);
+            this.snapshotManager.setCodebaseIndexed(codebasePath, decision.stats, decision.indexFingerprint, "verified", collectionName);
             this.saveSnapshotIfSupported();
             const recoveryMode = decision.reason === "valid_marker_runtime_mismatch"
                 ? " using completion marker proof from a different runtime fingerprint"
@@ -691,11 +715,48 @@ export class ToolHandlers {
         return DEFAULT_MANAGE_RETRY_AFTER_MS;
     }
     buildStaleLocalHint(codebasePath, reason) {
+        const preferSync = this.canSyncStaleLocal(codebasePath, reason);
+        const preferRepair = !preferSync && reason === "missing_marker_doc";
         return {
             completionProof: reason,
-            recommendedAction: this.buildCreateHint(codebasePath)
+            recommendedAction: preferSync
+                ? this.buildSyncHint(codebasePath)
+                : preferRepair
+                    ? this.buildRepairHint(codebasePath)
+                    : this.buildCreateHint(codebasePath),
+            ...(preferSync ? { sync: this.buildSyncHint(codebasePath) } : {}),
+            ...(preferRepair ? { create: this.buildCreateHint(codebasePath) } : {})
         };
     }
+    getSnapshotCollectionName(codebasePath) {
+        const fromSnapshot = this.snapshotCapabilities().getCodebaseCollectionName?.(codebasePath);
+        if (typeof fromSnapshot === 'string' && fromSnapshot.trim().length > 0) {
+            return fromSnapshot.trim();
+        }
+        const fromInfo = this.getSnapshotCodebaseInfo(codebasePath)?.collectionName;
+        return typeof fromInfo === 'string' && fromInfo.trim().length > 0
+            ? fromInfo.trim()
+            : undefined;
+    }
+    canSyncStaleLocal(codebasePath, reason) {
+        if (reason !== "missing_marker_doc") {
+            return false;
+        }
+        const info = this.getSnapshotCodebaseInfo(codebasePath);
+        if (!info || (info.status !== 'indexed' && info.status !== 'sync_completed')) {
+            return false;
+        }
+        if (info.fingerprintSource !== 'verified' || !info.indexFingerprint) {
+            return false;
+        }
+        if (!this.getSnapshotCollectionName(codebasePath)) {
+            return false;
+        }
+        if (!this.fingerprintsEqual(info.indexFingerprint, this.runtimeFingerprint)) {
+            return false;
+        }
+        return true;
+    }
     buildStaleLocalMessage(codebasePath, requestedPath, reason) {
         const requestedPathDetail = requestedPath !== codebasePath
             ? ` Requested path: '${requestedPath}'.`
@@ -771,15 +832,26 @@ export class ToolHandlers {
             },
         };
     }
-    recoverIndexedSnapshotFromCompletionProof(codebasePath, completionProof) {
+    async recoverIndexedSnapshotFromCompletionProof(codebasePath, completionProof) {
         const recovered = this.extractIndexedRecoveryFromCompletionProof(completionProof);
         if (!recovered) {
             return false;
         }
-        this.snapshotManager.setCodebaseIndexed(codebasePath, recovered.stats, recovered.indexFingerprint, 'verified');
+        const collectionName = await this.getActiveIndexedCollectionNameForSnapshotRecovery(codebasePath);
+        this.snapshotManager.setCodebaseIndexed(codebasePath, recovered.stats, recovered.indexFingerprint, 'verified', collectionName);
         this.saveSnapshotIfSupported();
         return true;
     }
+    async getActiveIndexedCollectionNameForSnapshotRecovery(codebasePath) {
+        const context = this.context;
+        if (typeof context.getActiveIndexedCollectionName !== 'function') {
+            return undefined;
+        }
+        const collectionName = await context.getActiveIndexedCollectionName(codebasePath);
+        return typeof collectionName === 'string' && collectionName.trim().length > 0
+            ? collectionName.trim()
+            : undefined;
+    }
     refreshSnapshotStateFromDisk() {
         const snapshotManager = this.snapshotManager;
         if (typeof snapshotManager.refreshFromDiskIfChanged !== 'function') {
@@ -818,7 +890,11 @@ export class ToolHandlers {
         }
         let collectionName;
         try {
-            if (typeof context.getActiveIndexedCollectionName === 'function') {
+            const snapshotCollectionName = this.getSnapshotCollectionName(codebasePath);
+            if (snapshotCollectionName) {
+                collectionName = snapshotCollectionName;
+            }
+            else if (typeof context.getActiveIndexedCollectionName === 'function') {
                 const activeCollectionName = await context.getActiveIndexedCollectionName(codebasePath);
                 if (typeof activeCollectionName === 'string' && activeCollectionName.trim().length > 0) {
                     collectionName = activeCollectionName;
@@ -1179,6 +1255,7 @@ export class ToolHandlers {
     }
     buildRequiresReindexFileOutlinePayload(codebasePath, input, detail, reason = 'requires_reindex') {
         const detailLine = detail ? `${detail}\n\n` : '';
+        const preferRepair = reason === 'missing_symbol_registry' || reason === 'missing_relationship_sidecar';
         return {
             status: 'requires_reindex',
             reason,
@@ -1186,8 +1263,11 @@ export class ToolHandlers {
             file: input.file,
             outline: null,
             hasMore: false,
-            message: `${detailLine}Relationship-backed navigation sidecars are missing or incompatible. Please run manage_index with {"action":"reindex","path":"${codebasePath}"}.`,
+            message: preferRepair
+                ? `${detailLine}Relationship-backed navigation sidecars are missing. Please run manage_index with {"action":"repair","path":"${codebasePath}"}.`
+                : `${detailLine}Relationship-backed navigation sidecars are missing or incompatible. Please run manage_index with {"action":"reindex","path":"${codebasePath}"}.`,
             hints: {
+                ...(preferRepair ? { repair: this.buildRepairHint(codebasePath) } : {}),
                 reindex: this.buildReindexHint(codebasePath)
             }
         };
@@ -1304,6 +1384,9 @@ export class ToolHandlers {
     async handleReindexCodebase(args) {
         return this.manageIndexingHandlers.handleReindexCodebase(args);
     }
+    async handleRepairIndex(args) {
+        return this.manageIndexingHandlers.handleRepairIndex(args);
+    }
     async handleSearchCode(args) {
         const scope = (typeof args.scope === 'string' ? args.scope : 'runtime');
         const resultMode = (typeof args.resultMode === 'string' ? args.resultMode : 'grouped');
@@ -1382,8 +1465,11 @@ export class ToolHandlers {
                 buildFreshnessBlockedSearchPayload: (codebasePath, freshnessDecision, searchContext) => this.buildFreshnessBlockedSearchPayload(codebasePath, freshnessDecision, searchContext),
                 buildManageIndexRecommendedAction: (action, codebasePath, rationale) => this.buildManageIndexRecommendedAction(action, codebasePath, rationale),
                 buildCreateHint: (codebasePath) => this.buildCreateHint(codebasePath),
+                buildSyncHint: (codebasePath) => this.buildSyncHint(codebasePath),
+                buildRepairHint: (codebasePath) => this.buildRepairHint(codebasePath),
                 buildStaleLocalHint: (codebasePath, reason) => this.buildStaleLocalHint(codebasePath, reason),
                 buildStaleLocalMessage: (codebasePath, requestedPath, reason) => this.buildStaleLocalMessage(codebasePath, requestedPath, reason),
+                canSyncStaleLocal: (codebasePath, reason) => this.canSyncStaleLocal(codebasePath, reason),
                 withProofDebugHint: (payload, proofDebugHint) => this.withProofDebugHint(payload, proofDebugHint),
                 isPartialIndexNavigationUnavailable: (info) => this.isPartialIndexNavigationUnavailable(info),
                 partialIndexWarnings: [

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

@@ -1,4 +1,4 @@
-import { Context, IndexCompletionMarkerDocument } from "@zokizuan/satori-core";
+import { Context } from "@zokizuan/satori-core";
 import type { SnapshotManager } from "./snapshot.js";
 import type { SyncManager } from "./sync.js";
 import { ManageIndexAction } from "./manage-types.js";
@@ -44,14 +44,15 @@ type ManageIndexingHandlersHost = {
     getSnapshotIndexingCodebases(): string[];
     getSnapshotCodebaseInfo(codebasePath: string): Record<string, unknown> | undefined;
     getSnapshotIndexedCodebases(): string[];
-    buildManageActionBlockedMessage(codebasePath: string, action: "create" | "reindex"): string;
+    buildManageActionBlockedMessage(codebasePath: string, action: "create" | "reindex" | "repair"): string;
+    buildCreateHint(codebasePath: string): Record<string, unknown>;
     buildStatusHint(codebasePath: string): Record<string, unknown>;
     getManageRetryAfterMs(): number;
     buildIndexingMetadata(codebasePath: string): Record<string, unknown> | undefined;
     buildReindexInstruction(codebasePath: string, detail?: string): string;
     buildManageRequiresReindexHints(codebasePath: string): Record<string, unknown>;
     validateCompletionProof(codebasePath: string): Promise<CompletionProofValidationResult>;
-    recoverIndexedSnapshotFromCompletionProof(codebasePath: string, proof: CompletionProofValidationResult): boolean;
+    recoverIndexedSnapshotFromCompletionProof(codebasePath: string, proof: CompletionProofValidationResult): Promise<boolean>;
     isZillizBackend(): boolean;
     resolveCollectionName(codebasePath: string): string;
     dropZillizCollectionForCreate(collectionName: string): Promise<{
@@ -67,8 +68,8 @@ type ManageIndexingHandlersHost = {
     getContextActiveIgnorePatterns(codebasePath: string): string[];
     getContextIndexedExtensions(codebasePath: string): string[];
     canonicalizeCodebasePath(codebasePath: string): string;
-    writeIndexCompletionMarker(codebasePath: string, marker: IndexCompletionMarkerDocument): Promise<void>;
     pruneIndexedCollectionFamily(codebasePath: string, keepCollectionName: string): Promise<string[]>;
+    pruneUnprovenStagedCollectionFamily(codebasePath: string): Promise<string[]>;
     getContextTrackedRelativePaths(codebasePath: string): string[];
     setIndexingStats(stats: {
         indexedFiles: number;
@@ -82,8 +83,11 @@ type ManageIndexingHandlersHost = {
 export declare class ManageIndexingHandlers {
     private readonly host;
     constructor(host: ManageIndexingHandlersHost);
+    private isStagedCollectionName;
+    private cleanupFailedStagedCollection;
     handleIndexCodebase(args: IndexCodebaseArgs): Promise<ToolTextResponse>;
     handleReindexCodebase(args: ReindexCodebaseArgs): Promise<ToolTextResponse>;
+    handleRepairIndex(args: Record<string, unknown>): Promise<ToolTextResponse>;
     private startBackgroundIndexing;
 }
 export {};

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

@@ -1,8 +1,24 @@
 import * as fs from "fs";
 import * as crypto from "node:crypto";
-import { COLLECTION_LIMIT_MESSAGE, RemoteCollectionDeletePendingError, } from "@zokizuan/satori-core";
+import { COLLECTION_LIMIT_MESSAGE, deleteCollectionWithVerification, RemoteCollectionDeletePendingError, } from "@zokizuan/satori-core";
 import { classifyVectorBackendError, } from "./backend-diagnostics.js";
 import { ensureAbsolutePath, trackCodebasePath } from "../utils.js";
+function isMatchingVerifiedFingerprint(info, runtimeFingerprint) {
+    if (info?.fingerprintSource !== "verified") {
+        return undefined;
+    }
+    const fingerprint = info.indexFingerprint;
+    if (!fingerprint || typeof fingerprint !== "object") {
+        return undefined;
+    }
+    const record = fingerprint;
+    const matches = record.embeddingProvider === runtimeFingerprint.embeddingProvider
+        && record.embeddingModel === runtimeFingerprint.embeddingModel
+        && Number(record.embeddingDimension) === Number(runtimeFingerprint.embeddingDimension)
+        && record.vectorStoreProvider === runtimeFingerprint.vectorStoreProvider
+        && record.schemaVersion === runtimeFingerprint.schemaVersion;
+    return matches ? fingerprint : undefined;
+}
 const COLLECTION_LIMIT_PATTERNS = [
     /exceeded the limit number of collections/i,
     /collection limit/i,
@@ -96,6 +112,21 @@ export class ManageIndexingHandlers {
     constructor(host) {
         this.host = host;
     }
+    isStagedCollectionName(collectionName) {
+        return typeof collectionName === "string" && collectionName.includes("__gen_");
+    }
+    async cleanupFailedStagedCollection(codebasePath, collectionName) {
+        if (!this.isStagedCollectionName(collectionName)) {
+            return;
+        }
+        try {
+            await deleteCollectionWithVerification(this.host.context.getVectorStore(), collectionName);
+            console.log(`[BACKGROUND-INDEX] Cleaned failed staged collection '${collectionName}' for '${codebasePath}'.`);
+        }
+        catch (cleanupError) {
+            console.warn(`[BACKGROUND-INDEX] Failed to clean staged collection '${collectionName}' after indexing failure for '${codebasePath}': ${formatUnknownError(cleanupError)}`);
+        }
+    }
     async handleIndexCodebase(args) {
         const { path: codebasePath, force, customExtensions, ignorePatterns, zillizDropCollection } = args;
         const forceReindex = force || false;
@@ -149,7 +180,7 @@ export class ManageIndexingHandlers {
             const isIndexedInSnapshot = this.host.getSnapshotIndexedCodebases().includes(absolutePath);
             if (!forceReindex && !isIndexedInSnapshot) {
                 const proof = await this.host.validateCompletionProof(absolutePath);
-                if (this.host.recoverIndexedSnapshotFromCompletionProof(absolutePath, proof)) {
+                if (await this.host.recoverIndexedSnapshotFromCompletionProof(absolutePath, proof)) {
                     if (proof.outcome === "fingerprint_mismatch") {
                         return this.host.manageResponse(manageAction, absolutePath, "requires_reindex", this.host.buildReindexInstruction(absolutePath, "Recovered local readiness from completion marker proof, but the current runtime fingerprint does not match the existing index."), {
                             ...preflightOptions,
@@ -200,6 +231,10 @@ export class ManageIndexingHandlers {
             }
             const stagedCollectionName = this.host.resolveStagedCollectionName(absolutePath, `run_${crypto.randomUUID()}`);
             try {
+                const prunedStagedCollections = await this.host.pruneUnprovenStagedCollectionFamily(absolutePath);
+                if (prunedStagedCollections.length > 0) {
+                    console.log(`[INDEX-VALIDATION] 🧹 Removed ${prunedStagedCollections.length} unproven staged collection(s): ${prunedStagedCollections.join(", ")}`);
+                }
                 console.log("[INDEX-VALIDATION] 🔍 Validating collection creation capability");
                 const canCreateCollection = await this.host.context.getVectorStore().checkCollectionLimit();
                 if (!canCreateCollection) {
@@ -332,12 +367,89 @@ export class ManageIndexingHandlers {
             __reindexPreflight: forwardedPreflight,
         });
     }
+    async handleRepairIndex(args) {
+        const codebasePath = args.path;
+        if (typeof codebasePath !== "string" || codebasePath.trim().length === 0) {
+            return this.host.manageResponse("repair", "", "error", "Error: Path is required.");
+        }
+        let absolutePath = codebasePath;
+        try {
+            absolutePath = ensureAbsolutePath(codebasePath);
+            if (!fs.existsSync(absolutePath)) {
+                return this.host.manageResponse("repair", absolutePath, "error", `Error: Path '${absolutePath}' does not exist. Original input: '${codebasePath}'`);
+            }
+            const stat = fs.statSync(absolutePath);
+            if (!stat.isDirectory()) {
+                return this.host.manageResponse("repair", absolutePath, "error", `Error: Path '${absolutePath}' is not a directory`);
+            }
+            const runtimeOwnerConflict = await this.host.buildRuntimeOwnerConflictResponseIfBlocked("repair", absolutePath);
+            if (runtimeOwnerConflict) {
+                return runtimeOwnerConflict;
+            }
+            if (this.host.getSnapshotIndexingCodebases().includes(absolutePath)) {
+                return this.host.manageResponse("repair", absolutePath, "not_ready", this.host.buildManageActionBlockedMessage(absolutePath, "repair"), {
+                    reason: "indexing",
+                    hints: {
+                        status: this.host.buildStatusHint(absolutePath),
+                        retryAfterMs: this.host.getManageRetryAfterMs(),
+                        indexing: this.host.buildIndexingMetadata(absolutePath),
+                    },
+                });
+            }
+            const trustedFingerprint = isMatchingVerifiedFingerprint(this.host.getSnapshotCodebaseInfo(absolutePath), this.host.runtimeFingerprint);
+            const result = await this.host.context.repairIndex(absolutePath, { trustedFingerprint });
+            if (result.status === "ok") {
+                await this.host.rebuildCallGraphForIndex(absolutePath);
+                await this.host.touchWatchedCodebase(absolutePath);
+                const stats = {
+                    indexedFiles: result.indexedFiles || 0,
+                    totalChunks: result.totalChunks || 0,
+                    status: "completed"
+                };
+                this.host.snapshotManager.setCodebaseIndexed(absolutePath, stats, this.host.runtimeFingerprint, "verified", result.collectionName);
+                const trackedRelativePaths = result.trackedRelativePaths;
+                this.host.snapshotManager.setCodebaseIndexManifest(absolutePath, Array.isArray(trackedRelativePaths)
+                    ? trackedRelativePaths.filter((entry) => typeof entry === "string")
+                    : this.host.getContextTrackedRelativePaths(absolutePath));
+                this.host.setIndexingStats(stats);
+                this.host.saveSnapshotIfSupported();
+                const warningsArray = Array.isArray(result.warnings) ? result.warnings : [];
+                return this.host.manageResponse("repair", absolutePath, "ok", result.message, {
+                    warnings: warningsArray,
+                });
+            }
+            else if (result.status === "requires_reindex") {
+                return this.host.manageResponse("repair", absolutePath, "requires_reindex", result.message, {
+                    reason: "requires_reindex",
+                    hints: this.host.buildManageRequiresReindexHints(absolutePath),
+                });
+            }
+            else {
+                return this.host.manageResponse("repair", absolutePath, "blocked", result.message, {
+                    reason: result.reason || "needs_create",
+                    hints: {
+                        create: this.host.buildCreateHint(absolutePath),
+                        missingCount: result.missingCount,
+                    }
+                });
+            }
+        }
+        catch (error) {
+            console.error("Error in handleRepairIndex:", error);
+            const vectorBackendDiagnostic = classifyVectorBackendError(error);
+            if (vectorBackendDiagnostic) {
+                return this.host.manageVectorBackendResponse("repair", absolutePath, vectorBackendDiagnostic);
+            }
+            return this.host.manageResponse("repair", absolutePath, "error", `Error performing repair: ${formatUnknownError(error)}`);
+        }
+    }
     async startBackgroundIndexing(codebasePath, forceReindex, writeCollectionName) {
         const absolutePath = codebasePath;
         let lastSaveTime = 0;
+        let targetCollectionName;
         try {
             console.log(`[BACKGROUND-INDEX] Starting background indexing for: ${absolutePath}`);
-            const targetCollectionName = typeof writeCollectionName === "string" && writeCollectionName.trim().length > 0
+            targetCollectionName = typeof writeCollectionName === "string" && writeCollectionName.trim().length > 0
                 ? writeCollectionName
                 : this.host.resolveCollectionName(absolutePath);
             this.host.setWriteCollectionOverride(absolutePath, targetCollectionName);
@@ -370,15 +482,6 @@ export class ManageIndexingHandlers {
                 console.log(`[BACKGROUND-INDEX] Progress: ${progress.phase} - ${progress.percentage}% (${progress.current}/${progress.total})`);
             });
             console.log(`[BACKGROUND-INDEX] ✅ Indexing completed successfully! Files: ${stats.indexedFiles}, Chunks: ${stats.totalChunks}`);
-            await this.host.writeIndexCompletionMarker(absolutePath, {
-                kind: "satori_index_completion_v1",
-                codebasePath: this.host.canonicalizeCodebasePath(absolutePath),
-                fingerprint: this.host.runtimeFingerprint,
-                indexedFiles: stats.indexedFiles,
-                totalChunks: stats.totalChunks,
-                completedAt: new Date().toISOString(),
-                runId: `run_${crypto.randomUUID()}`,
-            });
             try {
                 const droppedCollections = await this.host.pruneIndexedCollectionFamily(absolutePath, targetCollectionName);
                 if (droppedCollections.length > 0) {
@@ -388,7 +491,7 @@ export class ManageIndexingHandlers {
             catch (pruneError) {
                 console.warn(`[BACKGROUND-INDEX] Failed to retire superseded generations for '${absolutePath}': ${formatUnknownError(pruneError)}`);
             }
-            this.host.snapshotManager.setCodebaseIndexed(absolutePath, stats, this.host.runtimeFingerprint, "verified");
+            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);
@@ -413,6 +516,7 @@ export class ManageIndexingHandlers {
             catch (clearError) {
                 console.warn(`[BACKGROUND-INDEX] Failed to clear completion marker after indexing error for '${absolutePath}': ${formatUnknownError(clearError)}`);
             }
+            await this.cleanupFailedStagedCollection(absolutePath, targetCollectionName);
             this.host.snapshotManager.setCodebaseIndexFailed(absolutePath, errorMessage, this.host.getSnapshotIndexingProgress(absolutePath));
             this.host.saveSnapshotIfSupported();
             console.error(`[BACKGROUND-INDEX] Indexing failed for ${absolutePath}: ${errorMessage}`);

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

@@ -40,8 +40,10 @@ type ManageMaintenanceHandlersHost = {
     buildReindexInstruction(codebasePath: string, detail?: string): string;
     buildCompatibilityStatusLines(codebasePath: string): string;
     buildManageRequiresReindexHints(codebasePath: string): Record<string, unknown>;
+    buildSyncHint(codebasePath: string): Record<string, unknown>;
     buildStaleLocalHint(codebasePath: string, reason: string): Record<string, unknown>;
     buildStaleLocalMessage(codebasePath: string, requestedPath: string, reason: string): string;
+    canSyncStaleLocal(codebasePath: string, reason: string): boolean;
     enforceFingerprintGate(codebasePath: string): {
         blockedResponse?: ToolTextResponse;
         message?: string;

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

@@ -208,11 +208,15 @@ export class ManageMaintenanceHandlers {
                 envelopePath = trackedRootState.codebasePath;
                 envelopeStatus = "not_indexed";
                 envelopeReason = "not_indexed";
+                const syncable = this.host.canSyncStaleLocal(trackedRootState.codebasePath, trackedRootState.reason);
                 envelopeHints = {
+                    ...(syncable ? { sync: this.host.buildSyncHint(trackedRootState.codebasePath) } : {}),
                     create: this.host.buildCreateHint(trackedRootState.codebasePath),
                     staleLocal: this.host.buildStaleLocalHint(trackedRootState.codebasePath, trackedRootState.reason),
                 };
-                statusMessage = `❌ ${this.host.buildStaleLocalMessage(trackedRootState.codebasePath, absolutePath, trackedRootState.reason)} Run manage_index with {"action":"create","path":"${trackedRootState.codebasePath}"} to repair it.`;
+                const nextAction = syncable ? "sync" : trackedRootState.reason === "missing_marker_doc" ? "repair" : "create";
+                const nextVerb = syncable ? "sync it" : nextAction === "repair" ? "repair it" : "create it";
+                statusMessage = `❌ ${this.host.buildStaleLocalMessage(trackedRootState.codebasePath, absolutePath, trackedRootState.reason)} Run manage_index with {"action":"${nextAction}","path":"${trackedRootState.codebasePath}"} to ${nextVerb}.`;
             }
             else if (trackedRootState.state === "missing_collection") {
                 envelopePath = trackedRootState.codebasePath;

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

@@ -1,7 +1,7 @@
 import { WarningCode } from "./warnings.js";
-export type ManageIndexAction = "create" | "reindex" | "sync" | "status" | "clear";
+export type ManageIndexAction = "create" | "reindex" | "sync" | "status" | "clear" | "repair";
 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";
+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";
 export type ManageReindexPreflightOutcome = "reindex_required" | "reindex_unnecessary_ignore_only" | "unknown" | "probe_failed";
 export interface ManageIndexToolHint {

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

@@ -31,7 +31,7 @@ export type SearchFrontDoorHost = {
     buildRequiresReindexPayload: (codebasePath: string, detail: string | undefined, searchContext: SearchFrontDoorSearchContext) => SearchResponseEnvelope;
     buildNotReadySearchPayload: (codebasePath: string, searchContext: SearchFrontDoorSearchContext) => SearchResponseEnvelope;
     buildFreshnessBlockedSearchPayload: (codebasePath: string, freshnessDecision: FreshnessDecision, searchContext: SearchFrontDoorSearchContext) => SearchResponseEnvelope | null;
-    buildManageIndexRecommendedAction: (action: "create" | "reindex" | "sync" | "status", codebasePath: string, rationale: string) => SearchRecommendedNextAction;
+    buildManageIndexRecommendedAction: (action: "create" | "reindex" | "sync" | "status" | "repair", codebasePath: string, rationale: string) => SearchRecommendedNextAction;
     buildCreateHint: (codebasePath: string) => {
         tool: string;
         args: {
@@ -39,8 +39,23 @@ export type SearchFrontDoorHost = {
             path: string;
         };
     };
+    buildSyncHint: (codebasePath: string) => {
+        tool: string;
+        args: {
+            action: string;
+            path: string;
+        };
+    };
+    buildRepairHint: (codebasePath: string) => {
+        tool: string;
+        args: {
+            action: string;
+            path: string;
+        };
+    };
     buildStaleLocalHint: (codebasePath: string, reason: CompletionProofReason) => Record<string, unknown>;
     buildStaleLocalMessage: (codebasePath: string, requestedPath: string, reason: CompletionProofReason) => string;
+    canSyncStaleLocal: (codebasePath: string, reason: CompletionProofReason) => boolean;
     withProofDebugHint: <T extends object>(payload: T, proofDebugHint?: CompletionProbeDebugHint) => T;
     isPartialIndexNavigationUnavailable: (info: unknown) => boolean;
     partialIndexWarnings: readonly string[];

package/dist/core/search-frontdoor.js

@@ -48,6 +48,9 @@ function buildBlockedReadinessPayload(state, searchContext, host) {
         };
     }
     if (state.state === "stale_local") {
+        const preferSync = host.canSyncStaleLocal(state.codebasePath, state.reason);
+        const preferRepair = !preferSync && state.reason === "missing_marker_doc";
+        const action = preferSync ? "sync" : preferRepair ? "repair" : "create";
         return {
             status: "not_indexed",
             reason: "not_indexed",
@@ -59,8 +62,14 @@ function buildBlockedReadinessPayload(state, searchContext, host) {
             resultMode: searchContext.resultMode,
             freshnessDecision: null,
             message: host.buildStaleLocalMessage(state.codebasePath, searchContext.path, state.reason),
-            recommendedNextAction: host.buildManageIndexRecommendedAction("create", state.codebasePath, "Create a fresh index because local readiness metadata is stale."),
+            recommendedNextAction: host.buildManageIndexRecommendedAction(action, state.codebasePath, preferSync
+                ? "Run incremental sync; the local snapshot proves the committed collection and can restore the missing completion marker."
+                : preferRepair
+                    ? "Repair local readiness because completion marker proof is missing and no syncable snapshot collection is available."
+                    : "Create a fresh index because local readiness metadata is stale."),
             hints: {
+                ...(preferSync ? { sync: host.buildSyncHint(state.codebasePath) } : {}),
+                ...(preferRepair ? { repair: host.buildRepairHint(state.codebasePath) } : {}),
                 create: host.buildCreateHint(state.codebasePath),
                 staleLocal: host.buildStaleLocalHint(state.codebasePath, state.reason),
             },
@@ -89,20 +98,24 @@ export async function runSearchFrontDoor(input, host) {
     }
     trackCodebasePath(absolutePath);
     const trackedRootState = await host.prepareInitialTrackedRootRead(absolutePath);
-    const blockedReadinessPayload = buildBlockedReadinessPayload(trackedRootState, searchContext, host);
-    if (blockedReadinessPayload) {
-        return {
-            kind: "blocked",
-            payload: blockedReadinessPayload,
-        };
+    const canSyncInitialStaleLocal = trackedRootState.state === "stale_local"
+        && host.canSyncStaleLocal(trackedRootState.codebasePath, trackedRootState.reason);
+    if (!canSyncInitialStaleLocal) {
+        const blockedReadinessPayload = buildBlockedReadinessPayload(trackedRootState, searchContext, host);
+        if (blockedReadinessPayload) {
+            return {
+                kind: "blocked",
+                payload: blockedReadinessPayload,
+            };
+        }
     }
-    if (trackedRootState.state !== "ready") {
+    if (trackedRootState.state !== "ready" && !canSyncInitialStaleLocal) {
         throw new Error(`Unexpected non-ready tracked root state after readiness gating: ${trackedRootState.state}`);
     }
-    let searchableRoot = trackedRootState.root;
-    let effectiveRoot = searchableRoot.path || absolutePath;
-    let proofDebugHint = trackedRootState.proofDebugHint;
-    let partialIndexSearchWarnings = buildPartialIndexWarnings(host, searchableRoot);
+    let searchableRoot = trackedRootState.state === "ready" ? trackedRootState.root : null;
+    let effectiveRoot = searchableRoot?.path || (trackedRootState.state === "stale_local" ? trackedRootState.codebasePath : absolutePath);
+    let proofDebugHint = trackedRootState.state === "ready" ? trackedRootState.proofDebugHint : undefined;
+    let partialIndexSearchWarnings = searchableRoot ? buildPartialIndexWarnings(host, searchableRoot) : [];
     const freshnessDecision = await host.ensureSearchFreshness(effectiveRoot);
     host.noteFreshnessMode(freshnessDecision.mode);
     const freshnessBlockedPayload = host.buildFreshnessBlockedSearchPayload(effectiveRoot, freshnessDecision, searchContext);

package/dist/core/snapshot.d.ts

@@ -83,6 +83,7 @@ export declare class SnapshotManager {
     getIndexingProgress(codebasePath: string): number | undefined;
     getCodebaseStatus(codebasePath: string): CodebaseInfo['status'] | 'not_found';
     getCodebaseInfo(codebasePath: string): CodebaseInfo | undefined;
+    getCodebaseCollectionName(codebasePath: string): string | undefined;
     getAllCodebases(): Array<{
         path: string;
         info: CodebaseInfo;
@@ -97,13 +98,13 @@ export declare class SnapshotManager {
         indexedFiles: number;
         totalChunks: number;
         status: 'completed' | 'limit_reached';
-    }, indexFingerprint?: IndexFingerprint, fingerprintSource?: FingerprintSource): void;
+    }, indexFingerprint?: IndexFingerprint, fingerprintSource?: FingerprintSource, collectionName?: string): void;
     setCodebaseIndexFailed(codebasePath: string, errorMessage: string, lastAttemptedPercentage?: number): void;
     setCodebaseSyncCompleted(codebasePath: string, stats: {
         added: number;
         removed: number;
         modified: number;
-    }, indexFingerprint?: IndexFingerprint, fingerprintSource?: FingerprintSource): void;
+    }, indexFingerprint?: IndexFingerprint, fingerprintSource?: FingerprintSource, collectionName?: string): void;
     setCodebaseRequiresReindex(codebasePath: string, reason: AccessGateReason, message?: string): void;
     private recoverCodebaseFromResolvedFingerprintMismatch;
     setCodebaseCallGraphSidecar(codebasePath: string, sidecar: CallGraphSidecarInfo): void;

package/dist/core/snapshot.js

@@ -384,6 +384,9 @@ export class SnapshotManager {
         if (rawInfo.indexFingerprint !== undefined && !this.isValidIndexFingerprint(rawInfo.indexFingerprint)) {
             return false;
         }
+        if (rawInfo.collectionName !== undefined && typeof rawInfo.collectionName !== "string") {
+            return false;
+        }
         if (rawInfo.fingerprintSource !== undefined && rawInfo.fingerprintSource !== "verified" && rawInfo.fingerprintSource !== "assumed_v2") {
             return false;
         }
@@ -802,6 +805,12 @@ export class SnapshotManager {
     getCodebaseInfo(codebasePath) {
         return this.codebaseInfoMap.get(codebasePath);
     }
+    getCodebaseCollectionName(codebasePath) {
+        const collectionName = this.codebaseInfoMap.get(codebasePath)?.collectionName;
+        return typeof collectionName === "string" && collectionName.trim().length > 0
+            ? collectionName.trim()
+            : undefined;
+    }
     getAllCodebases() {
         return Array.from(this.codebaseInfoMap.entries()).map(([p, info]) => ({ path: p, info }));
     }
@@ -849,6 +858,7 @@ export class SnapshotManager {
             indexFingerprint: existing?.indexFingerprint,
             fingerprintSource: existing?.fingerprintSource,
             reindexReason: existing?.reindexReason,
+            collectionName: existing?.collectionName,
             callGraphSidecar: existing?.callGraphSidecar,
             indexManifest: existing?.indexManifest,
             ignoreRulesVersion: existing?.ignoreRulesVersion,
@@ -858,15 +868,19 @@ export class SnapshotManager {
         this.markDirty();
         this.refreshDerivedState();
     }
-    setCodebaseIndexed(codebasePath, stats, indexFingerprint, fingerprintSource = 'verified') {
+    setCodebaseIndexed(codebasePath, stats, indexFingerprint, fingerprintSource = 'verified', collectionName) {
         this.markCodebasePresent(codebasePath);
         const existing = this.codebaseInfoMap.get(codebasePath);
+        const resolvedCollectionName = typeof collectionName === "string" && collectionName.trim().length > 0
+            ? collectionName.trim()
+            : existing?.collectionName;
         const info = {
             status: 'indexed',
             indexedFiles: stats.indexedFiles,
             totalChunks: stats.totalChunks,
             indexStatus: stats.status,
             lastUpdated: new Date().toISOString(),
+            collectionName: resolvedCollectionName,
             indexFingerprint: indexFingerprint || this.runtimeFingerprint,
             fingerprintSource,
             callGraphSidecar: existing?.callGraphSidecar,
@@ -886,6 +900,7 @@ export class SnapshotManager {
             errorMessage,
             lastAttemptedPercentage,
             lastUpdated: new Date().toISOString(),
+            collectionName: existing?.collectionName,
             indexFingerprint: existing?.indexFingerprint,
             fingerprintSource: existing?.fingerprintSource,
             callGraphSidecar: existing?.callGraphSidecar,
@@ -897,10 +912,13 @@ export class SnapshotManager {
         this.markDirty();
         this.refreshDerivedState();
     }
-    setCodebaseSyncCompleted(codebasePath, stats, indexFingerprint, fingerprintSource = 'verified') {
+    setCodebaseSyncCompleted(codebasePath, stats, indexFingerprint, fingerprintSource = 'verified', collectionName) {
         this.markCodebasePresent(codebasePath);
         const totalChanges = stats.added + stats.removed + stats.modified;
         const existing = this.codebaseInfoMap.get(codebasePath);
+        const resolvedCollectionName = typeof collectionName === "string" && collectionName.trim().length > 0
+            ? collectionName.trim()
+            : existing?.collectionName;
         const info = {
             status: 'sync_completed',
             added: stats.added,
@@ -908,6 +926,7 @@ export class SnapshotManager {
             modified: stats.modified,
             totalChanges,
             lastUpdated: new Date().toISOString(),
+            collectionName: resolvedCollectionName,
             indexFingerprint: indexFingerprint || existing?.indexFingerprint || this.runtimeFingerprint,
             fingerprintSource,
             callGraphSidecar: existing?.callGraphSidecar,
@@ -927,6 +946,7 @@ export class SnapshotManager {
             message: message || 'Index is incompatible with the current runtime fingerprint and must be rebuilt.',
             reindexReason: reason,
             lastUpdated: new Date().toISOString(),
+            collectionName: existing?.collectionName,
             indexFingerprint: existing?.indexFingerprint,
             fingerprintSource: existing?.fingerprintSource,
             callGraphSidecar: existing?.callGraphSidecar,
@@ -946,6 +966,7 @@ export class SnapshotManager {
             modified: 0,
             totalChanges: 0,
             lastUpdated: new Date().toISOString(),
+            collectionName: info.collectionName,
             indexFingerprint: info.indexFingerprint,
             fingerprintSource: info.fingerprintSource,
             callGraphSidecar: info.callGraphSidecar,

package/dist/core/sync.d.ts

@@ -39,6 +39,7 @@ interface SyncStats {
     modified: number;
     changedFiles: string[];
     navigationRecovery?: 'rebuilt' | 'failed';
+    collectionName?: string;
 }
 type WatchSyncReason = 'watch_event' | 'ignore_rules_changed';
 interface EnsureFreshnessOptions {

package/dist/core/sync.js

@@ -295,7 +295,12 @@ export class SyncManager {
         }
         try {
             // Incremental sync
-            const stats = await this.context.reindexByChange(codebasePath);
+            const collectionName = this.snapshotManager.getCodebaseCollectionName?.(codebasePath);
+            const syncOptions = {
+                ...(collectionName ? { targetCollectionName: collectionName } : {}),
+                maintainCompletionMarker: true,
+            };
+            const stats = await this.context.reindexByChange(codebasePath, undefined, syncOptions);
             if (typeof this.context.getTrackedRelativePaths === 'function') {
                 const trackedPaths = this.context.getTrackedRelativePaths(codebasePath);
                 if (typeof this.snapshotManager.setCodebaseIndexManifest === 'function') {
@@ -310,7 +315,7 @@ export class SyncManager {
                 return { mode: 'skipped_requires_reindex', stats };
             }
             // Persist Snapshot
-            this.snapshotManager.setCodebaseSyncCompleted(codebasePath, stats);
+            this.snapshotManager.setCodebaseSyncCompleted(codebasePath, stats, undefined, 'verified', stats.collectionName || collectionName);
             this.snapshotManager.saveCodebaseSnapshot();
             if (this.onSyncCompleted) {
                 await this.onSyncCompleted(codebasePath, {

package/dist/core/tool-response-builders.d.ts

@@ -23,7 +23,7 @@ type CallGraphContext = {
     limit: number;
 };
 export type ToolResponseBuildersHost = {
-    buildManageIndexRecommendedAction(action: "create" | "reindex" | "sync" | "status", codebasePath: string, rationale: string): SearchRecommendedNextAction;
+    buildManageIndexRecommendedAction(action: "create" | "reindex" | "sync" | "status" | "repair", codebasePath: string, rationale: string): SearchRecommendedNextAction;
     buildCreateHint(codebasePath: string): {
         tool: string;
         args: {
@@ -38,6 +38,13 @@ export type ToolResponseBuildersHost = {
             path: string;
         };
     };
+    buildRepairHint(codebasePath: string): {
+        tool: string;
+        args: {
+            action: string;
+            path: string;
+        };
+    };
     buildStatusHint(codebasePath: string): {
         tool: string;
         args: {

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

@@ -110,6 +110,7 @@ export class ToolResponseBuilders {
     }
     buildRequiresReindexCallGraphPayload(codebasePath, detail, context, reason = "requires_reindex") {
         const detailLine = detail ? `${detail}\n\n` : "";
+        const preferRepair = reason === "missing_symbol_registry" || reason === "missing_relationship_sidecar";
         return {
             status: "requires_reindex",
             supported: false,
@@ -126,8 +127,11 @@ export class ToolResponseBuilders {
             freshnessDecision: {
                 mode: "skipped_requires_reindex",
             },
-            message: `${detailLine}The index at '${codebasePath}' is incompatible with the current runtime and must be rebuilt. Please run manage_index with {"action":"reindex","path":"${codebasePath}"}.`,
+            message: preferRepair
+                ? `${detailLine}The index at '${codebasePath}' is missing navigation sidecars. Please run manage_index with {"action":"repair","path":"${codebasePath}"}.`
+                : `${detailLine}The index at '${codebasePath}' is incompatible with the current runtime and must be rebuilt. Please run manage_index with {"action":"reindex","path":"${codebasePath}"}.`,
             hints: {
+                ...(preferRepair ? { repair: this.host.buildRepairHint(codebasePath) } : {}),
                 reindex: this.host.buildReindexHint(codebasePath),
             },
             compatibility: this.host.buildCompatibilityDiagnostics(codebasePath),

package/dist/core/vector-backend-maintenance.js

@@ -1,6 +1,5 @@
 import { COLLECTION_LIMIT_MESSAGE, deleteCollectionWithVerification, } from "@zokizuan/satori-core";
 const SATORI_COLLECTION_PREFIXES = ["code_chunks_", "hybrid_code_chunks_"];
-const ZILLIZ_FREE_TIER_COLLECTION_LIMIT = 5;
 const MIN_RELIABLE_COLLECTION_CREATED_AT_MS = Date.UTC(2000, 0, 1);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -185,7 +184,7 @@ export class VectorBackendMaintenance {
             : "No Satori-managed collections were discovered.";
         return `${COLLECTION_LIMIT_MESSAGE}
 
-Reason: Zilliz free-tier clusters are capped at ${ZILLIZ_FREE_TIER_COLLECTION_LIMIT} collections, and this cluster has no remaining collection slots.
+Reason: The connected Zilliz cluster has no remaining collection slots.
 Target codebase: '${targetCodebasePath}'
 Target collection: '${targetCollectionName}'
 

package/dist/server/start-server.js

@@ -153,7 +153,10 @@ class ContextMcpServer {
                 : null;
             const decision = decideInterruptedIndexingRecovery(marker, this.runtimeFingerprint);
             if (decision.action === "promote_indexed") {
-                toolContext.snapshotManager.setCodebaseIndexed(codebasePath, decision.stats, decision.indexFingerprint, "verified");
+                const collectionName = typeof toolContext.context.getActiveIndexedCollectionName === "function"
+                    ? await toolContext.context.getActiveIndexedCollectionName(codebasePath) ?? undefined
+                    : undefined;
+                toolContext.snapshotManager.setCodebaseIndexed(codebasePath, decision.stats, decision.indexFingerprint, "verified", collectionName);
                 promotedCount++;
                 const recoveryMode = decision.reason === "valid_marker_runtime_mismatch"
                     ? "indexed (fingerprint recovered from marker; current runtime differs)"

package/dist/tools/manage_index.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { formatZodError } from "./types.js";
 import { classifyVectorBackendError, formatManageProviderConfigError, formatManageVectorBackendError, isMissingProviderConfigIssue } from "./setup-errors.js";
-const actionEnum = z.enum(["create", "reindex", "sync", "status", "clear"]);
+const actionEnum = z.enum(["create", "reindex", "sync", "status", "clear", "repair"]);
 const manageIndexInputSchema = z.object({
     action: actionEnum.describe("Required operation to run."),
     path: z.string().min(1).describe("ABSOLUTE path to the target codebase."),
@@ -13,7 +13,7 @@ const manageIndexInputSchema = z.object({
 });
 export const manageIndexTool = {
     name: "manage_index",
-    description: () => "Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action=\"sync\" for immediate convergence and action=\"reindex\" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action=\"status\" to observe progress.",
+    description: () => "Manage index lifecycle operations (create/reindex/sync/status/clear/repair) for a codebase path. repair rebuilds local readiness only when existing vector payload and trusted runtime fingerprint proof match; otherwise it refuses and asks for create/reindex. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action=\"sync\" for immediate convergence and action=\"reindex\" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action=\"status\" to observe progress.",
     inputSchemaZod: () => manageIndexInputSchema,
     execute: async (args, ctx) => {
         const parsed = manageIndexInputSchema.safeParse(args || {});
@@ -29,7 +29,7 @@ export const manageIndexTool = {
         const input = parsed.data;
         const providerOperation = input.action === "clear" || input.action === "status"
             ? "vector_only"
-            : (input.action === "create" || input.action === "reindex" || input.action === "sync")
+            : (input.action === "create" || input.action === "reindex" || input.action === "sync" || input.action === "repair")
                 ? "embedding_vector"
                 : null;
         let executionContext;
@@ -76,6 +76,9 @@ export const manageIndexTool = {
                 case 'clear':
                     response = await executionContext.toolHandlers.handleClearIndex(input);
                     break;
+                case 'repair':
+                    response = await executionContext.toolHandlers.handleRepairIndex(input);
+                    break;
                 default:
                     return {
                         content: [{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-mcp",
-  "version": "4.11.8",
+  "version": "4.11.13",
   "description": "Repo-aware MCP tools for AI coding agents: intent search, symbol navigation, exact reads, related paths, and freshness warnings.",
   "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": "1.6.4"
+    "@zokizuan/satori-core": "1.6.9"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",