@zokizuan/satori-mcp 4.6.0 → 4.8.0

package/README.md

@@ -157,7 +157,7 @@ No parameters.
   "mcpServers": {
     "satori": {
       "command": "npx",
-      "args": ["-y", "@zokizuan/satori-mcp@4.4.1"],
+      "args": ["-y", "@zokizuan/satori-mcp@4.8.0"],
       "timeout": 180000,
       "env": {
         "EMBEDDING_PROVIDER": "VoyageAI",
@@ -178,7 +178,7 @@ No parameters.
 ```toml
 [mcp_servers.satori]
 command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@4.4.1"]
+args = ["-y", "@zokizuan/satori-mcp@4.8.0"]
 startup_timeout_ms = 180000
 env = { EMBEDDING_PROVIDER = "VoyageAI", EMBEDDING_MODEL = "voyage-4-large", EMBEDDING_OUTPUT_DIMENSION = "1024", VOYAGEAI_API_KEY = "your-api-key", VOYAGEAI_RERANKER_MODEL = "rerank-2.5", MILVUS_ADDRESS = "your-milvus-endpoint", MILVUS_TOKEN = "your-milvus-token" }
 ```
@@ -228,10 +228,10 @@ Supported installer targets in Phase 1:
 Examples:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.1.1 install --client codex
-npx -y @zokizuan/satori-cli@0.1.1 install --client claude
-npx -y @zokizuan/satori-cli@0.1.1 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.1.1 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.2.0 install --client codex
+npx -y @zokizuan/satori-cli@0.2.0 install --client claude
+npx -y @zokizuan/satori-cli@0.2.0 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.2.0 uninstall --client codex
 ```
 
 Install and uninstall run before MCP session startup, only touch Satori-managed config, and copy/remove these packaged skills:

package/dist/cli/package-installability.js

@@ -55,7 +55,7 @@ function assertPublishedVersion(packageName, version, ownerPackageName, ownerPac
             stdio: ["ignore", "pipe", "pipe"],
         });
     }
-    catch (error) {
+    catch {
         if (relation === "self") {
             throw new CliError("E_USAGE", `Cannot install ${ownerPackageName}@${ownerPackageVersion} because that package version is not published on npm. Publish ${ownerPackageName}@${ownerPackageVersion} first or use a local dev server config instead.`, 2);
         }

package/dist/config.d.ts

@@ -42,6 +42,10 @@ export interface CodebaseIndexManifest {
     indexedPaths: string[];
     updatedAt: string;
 }
+export interface CodebaseClearTombstone {
+    clearedAt: string;
+    collectionName?: string;
+}
 export interface CodebaseSnapshotV1 {
     indexedCodebases: string[];
     indexingCodebases: string[] | Record<string, number>;
@@ -94,6 +98,7 @@ export interface CodebaseSnapshotV2 {
 export interface CodebaseSnapshotV3 {
     formatVersion: 'v3';
     codebases: Record<string, CodebaseInfo>;
+    clearTombstones?: Record<string, CodebaseClearTombstone>;
     lastUpdated: string;
 }
 export type CodebaseSnapshot = CodebaseSnapshotV1 | CodebaseSnapshotV2 | CodebaseSnapshotV3;

package/dist/config.js

@@ -169,7 +169,7 @@ export function showHelpMessage() {
     console.log(`
 Satori MCP Server
 
-Usage: npx -y @zokizuan/satori-mcp@4.4.1 [options]
+Usage: npx -y @zokizuan/satori-mcp@4.8.0 [options]
 
 Options:
   --help, -h                          Show this help message
@@ -206,16 +206,16 @@ Environment Variables:
 
 Examples:
   # Start MCP server with OpenAI and explicit Milvus address
-  OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.4.1
+  OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.8.0
 
   # Start MCP server with VoyageAI and specific model
-  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
+  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.8.0
 
   # Start MCP server with Gemini and specific model
-  EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
+  EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.8.0
 
   # Start MCP server with Ollama and specific model
-  EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
+  EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.8.0
         `);
 }
 //# sourceMappingURL=config.js.map

package/dist/core/completion-proof.d.ts

@@ -0,0 +1,24 @@
+import type { IndexFingerprint } from "../config.js";
+export type CompletionProofOutcome = "valid" | "stale_local" | "fingerprint_mismatch" | "probe_failed";
+export type CompletionProofReason = "missing_marker_doc" | "invalid_marker_kind" | "path_mismatch" | "invalid_payload" | "fingerprint_mismatch" | "probe_failed";
+export type CompletionProofValidationResult = {
+    outcome: CompletionProofOutcome;
+    reason?: CompletionProofReason;
+    marker?: {
+        kind?: string;
+        codebasePath?: string;
+        fingerprint?: unknown;
+        indexedFiles?: number;
+        totalChunks?: number;
+        completedAt?: string;
+        runId?: string;
+    };
+};
+export type CompletionMarkerReader = (codebasePath: string) => Promise<unknown>;
+export declare function validateCompletionProof(args: {
+    codebasePath: string;
+    runtimeFingerprint?: IndexFingerprint;
+    getIndexCompletionMarker?: CompletionMarkerReader;
+    onProbeError?: (error: unknown) => void;
+}): Promise<CompletionProofValidationResult>;
+//# sourceMappingURL=completion-proof.d.ts.map

package/dist/core/completion-proof.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+function trimTrailingSeparators(inputPath) {
+    const normalized = path.normalize(inputPath);
+    const parsedRoot = path.parse(normalized).root;
+    if (normalized === parsedRoot) {
+        return normalized;
+    }
+    return normalized.replace(/[\\/]+$/, "");
+}
+function canonicalizeCodebasePath(codebasePath) {
+    const resolved = path.resolve(codebasePath);
+    try {
+        const realPath = typeof fs.realpathSync.native === "function"
+            ? fs.realpathSync.native(resolved)
+            : fs.realpathSync(resolved);
+        return trimTrailingSeparators(realPath);
+    }
+    catch {
+        return trimTrailingSeparators(resolved);
+    }
+}
+function markerMatchesRuntimeFingerprint(marker, runtimeFingerprint) {
+    if (!runtimeFingerprint || typeof runtimeFingerprint !== "object") {
+        return true;
+    }
+    const fingerprint = marker?.fingerprint;
+    if (!fingerprint || typeof fingerprint !== "object") {
+        return false;
+    }
+    const record = fingerprint;
+    return record.embeddingProvider === runtimeFingerprint.embeddingProvider
+        && record.embeddingModel === runtimeFingerprint.embeddingModel
+        && Number(record.embeddingDimension) === Number(runtimeFingerprint.embeddingDimension)
+        && record.vectorStoreProvider === runtimeFingerprint.vectorStoreProvider
+        && record.schemaVersion === runtimeFingerprint.schemaVersion;
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number"
+        && Number.isInteger(value)
+        && value >= 0;
+}
+function validateMarkerShape(expectedCodebasePath, marker) {
+    if (!marker || typeof marker !== "object") {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    const record = marker;
+    if (record.kind !== "satori_index_completion_v1") {
+        return { ok: false, reason: "invalid_marker_kind" };
+    }
+    if (typeof record.codebasePath !== "string" || record.codebasePath.trim().length === 0) {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    if (!record.fingerprint || typeof record.fingerprint !== "object") {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    if (!isNonNegativeInteger(record.indexedFiles) || !isNonNegativeInteger(record.totalChunks)) {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    if (typeof record.completedAt !== "string" || Number.isNaN(Date.parse(record.completedAt))) {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    const expectedCanonical = canonicalizeCodebasePath(expectedCodebasePath);
+    const markerCanonical = canonicalizeCodebasePath(record.codebasePath);
+    if (expectedCanonical !== markerCanonical) {
+        return { ok: false, reason: "path_mismatch" };
+    }
+    return { ok: true };
+}
+export async function validateCompletionProof(args) {
+    const { codebasePath, runtimeFingerprint, getIndexCompletionMarker, onProbeError } = args;
+    if (typeof getIndexCompletionMarker !== "function") {
+        return { outcome: "probe_failed", reason: "probe_failed" };
+    }
+    let marker;
+    try {
+        marker = await getIndexCompletionMarker(codebasePath);
+    }
+    catch (error) {
+        onProbeError?.(error);
+        return { outcome: "probe_failed", reason: "probe_failed" };
+    }
+    if (!marker) {
+        return { outcome: "stale_local", reason: "missing_marker_doc" };
+    }
+    const markerShape = validateMarkerShape(codebasePath, marker);
+    if (!markerShape.ok) {
+        return {
+            outcome: "stale_local",
+            reason: markerShape.reason,
+            marker: marker
+        };
+    }
+    if (!markerMatchesRuntimeFingerprint(marker, runtimeFingerprint)) {
+        return {
+            outcome: "fingerprint_mismatch",
+            reason: "fingerprint_mismatch",
+            marker: marker
+        };
+    }
+    return {
+        outcome: "valid",
+        marker: marker
+    };
+}
+//# sourceMappingURL=completion-proof.js.map

package/dist/core/handlers.d.ts

@@ -33,10 +33,6 @@ export declare class ToolHandlers {
     private isIndexingStateStale;
     private recoverStaleIndexingStateIfNeeded;
     private buildManageActionBlockedMessage;
-    private markerMatchesRuntimeFingerprint;
-    private trimTrailingSeparators;
-    private canonicalizeCodebasePath;
-    private validateMarkerShape;
     private buildStaleLocalHint;
     private buildStaleLocalMessage;
     private withProofDebugHint;
@@ -72,6 +68,8 @@ export declare class ToolHandlers {
     private classifyNoiseCategory;
     private roundRatio;
     private normalizeRelativePathForIgnoreCheck;
+    private trimTrailingSeparators;
+    private canonicalizeCodebasePath;
     private loadRootGitignoreMatcher;
     private patternMatchesAnyPath;
     private filterNoiseHintPatternsByRootGitignore;

package/dist/core/handlers.js

@@ -3,13 +3,14 @@ import * as path from "path";
 import crypto from "node:crypto";
 import { execFileSync } from "node:child_process";
 import ignore from "ignore";
-import { COLLECTION_LIMIT_MESSAGE, getSupportedExtensionsForCapability, isLanguageCapabilitySupportedForExtension, isLanguageCapabilitySupportedForLanguage, } from "@zokizuan/satori-core";
+import { COLLECTION_LIMIT_MESSAGE, RemoteCollectionDeletePendingError, deleteCollectionWithVerification, getSupportedExtensionsForCapability, isLanguageCapabilitySupportedForExtension, isLanguageCapabilitySupportedForLanguage, } from "@zokizuan/satori-core";
 import { ensureAbsolutePath, truncateContent, trackCodebasePath } from "../utils.js";
 import { DEFAULT_WATCH_DEBOUNCE_MS } from "../config.js";
 import { SEARCH_CHANGED_FILES_CACHE_TTL_MS, SEARCH_CHANGED_FIRST_MULTIPLIER, SEARCH_CHANGED_FIRST_MAX_CHANGED_FILES, SEARCH_DIVERSITY_MAX_PER_FILE, SEARCH_DIVERSITY_MAX_PER_SYMBOL, SEARCH_DIVERSITY_RELAXED_FILE_CAP, SEARCH_MAX_CANDIDATES, SEARCH_MUST_RETRY_MULTIPLIER, SEARCH_MUST_RETRY_ROUNDS, SEARCH_NOISE_HINT_PATTERNS, SEARCH_GITIGNORE_FORCE_RELOAD_EVERY_N, SEARCH_NOISE_HINT_THRESHOLD, SEARCH_NOISE_HINT_TOP_K, SEARCH_OPERATOR_PREFIX_MAX_CHARS, SEARCH_PROXIMITY_WINDOW, SEARCH_RERANK_DOC_MAX_CHARS, SEARCH_RERANK_DOC_MAX_LINES, SEARCH_RERANK_RRF_K, SEARCH_RERANK_TOP_K, SEARCH_RERANK_WEIGHT, SEARCH_RRF_K, SCOPE_PATH_MULTIPLIERS, STALENESS_THRESHOLDS_MS } from "./search-constants.js";
 import { WARNING_CODES } from "./warnings.js";
 import { CallGraphSidecarManager } from "./call-graph.js";
 import { decideInterruptedIndexingRecovery } from "./indexing-recovery.js";
+import { validateCompletionProof as validateIndexCompletionProof } from "./completion-proof.js";
 const COLLECTION_LIMIT_PATTERNS = [
     /exceeded the limit number of collections/i,
     /collection limit/i,
@@ -110,6 +111,10 @@ function isCollectionLimitError(error) {
     }
     return COLLECTION_LIMIT_PATTERNS.some((pattern) => pattern.test(message));
 }
+function isBackendTimeoutError(error) {
+    const message = formatUnknownError(error);
+    return /DEADLINE_EXCEEDED|deadline exceeded|timeout|timed out/i.test(message);
+}
 export class ToolHandlers {
     constructor(context, snapshotManager, syncManager, runtimeFingerprint, capabilities, now = () => Date.now(), callGraphManager, reranker, gitignoreForceReloadEveryN = SEARCH_GITIGNORE_FORCE_RELOAD_EVERY_N) {
         this.indexingStats = null;
@@ -296,62 +301,6 @@ export class ToolHandlers {
         }
         return lines.join('\n');
     }
-    markerMatchesRuntimeFingerprint(marker) {
-        const fingerprint = marker?.fingerprint;
-        if (!fingerprint || typeof fingerprint !== 'object') {
-            return false;
-        }
-        return fingerprint.embeddingProvider === this.runtimeFingerprint.embeddingProvider
-            && fingerprint.embeddingModel === this.runtimeFingerprint.embeddingModel
-            && Number(fingerprint.embeddingDimension) === Number(this.runtimeFingerprint.embeddingDimension)
-            && fingerprint.vectorStoreProvider === this.runtimeFingerprint.vectorStoreProvider
-            && fingerprint.schemaVersion === this.runtimeFingerprint.schemaVersion;
-    }
-    trimTrailingSeparators(inputPath) {
-        const parsedRoot = path.parse(inputPath).root;
-        if (inputPath === parsedRoot) {
-            return inputPath;
-        }
-        return inputPath.replace(/[\\/]+$/, '');
-    }
-    canonicalizeCodebasePath(codebasePath) {
-        const resolved = path.resolve(codebasePath);
-        try {
-            const realPath = typeof fs.realpathSync.native === 'function'
-                ? fs.realpathSync.native(resolved)
-                : fs.realpathSync(resolved);
-            return this.trimTrailingSeparators(path.normalize(realPath));
-        }
-        catch {
-            return this.trimTrailingSeparators(path.normalize(resolved));
-        }
-    }
-    validateMarkerShape(expectedCodebasePath, marker) {
-        if (!marker || typeof marker !== 'object') {
-            return { ok: false, reason: 'invalid_payload' };
-        }
-        if (marker.kind !== 'satori_index_completion_v1') {
-            return { ok: false, reason: 'invalid_marker_kind' };
-        }
-        if (typeof marker.codebasePath !== 'string' || marker.codebasePath.trim().length === 0) {
-            return { ok: false, reason: 'invalid_payload' };
-        }
-        if (!marker.fingerprint || typeof marker.fingerprint !== 'object') {
-            return { ok: false, reason: 'invalid_payload' };
-        }
-        if (!Number.isFinite(Number(marker.indexedFiles)) || !Number.isFinite(Number(marker.totalChunks))) {
-            return { ok: false, reason: 'invalid_payload' };
-        }
-        if (typeof marker.completedAt !== 'string' || Number.isNaN(Date.parse(marker.completedAt))) {
-            return { ok: false, reason: 'invalid_payload' };
-        }
-        const expectedCanonical = this.canonicalizeCodebasePath(expectedCodebasePath);
-        const markerCanonical = this.canonicalizeCodebasePath(marker.codebasePath);
-        if (expectedCanonical !== markerCanonical) {
-            return { ok: false, reason: 'path_mismatch' };
-        }
-        return { ok: true };
-    }
     buildStaleLocalHint(codebasePath, reason) {
         return {
             completionProof: reason,
@@ -381,48 +330,16 @@ export class ToolHandlers {
         };
     }
     async validateCompletionProof(codebasePath) {
-        if (typeof this.context.getIndexCompletionMarker !== 'function') {
-            return {
-                outcome: 'probe_failed',
-                reason: 'probe_failed'
-            };
-        }
-        let marker;
-        try {
-            marker = await this.context.getIndexCompletionMarker(codebasePath);
-        }
-        catch (error) {
-            console.warn(`[INDEX-PROOF] Completion marker probe failed for '${codebasePath}': ${formatUnknownError(error)}`);
-            return {
-                outcome: 'probe_failed',
-                reason: 'probe_failed'
-            };
-        }
-        if (!marker) {
-            return {
-                outcome: 'stale_local',
-                reason: 'missing_marker_doc'
-            };
-        }
-        const markerShape = this.validateMarkerShape(codebasePath, marker);
-        if (!markerShape.ok) {
-            return {
-                outcome: 'stale_local',
-                reason: markerShape.reason,
-                marker
-            };
-        }
-        if (!this.markerMatchesRuntimeFingerprint(marker)) {
-            return {
-                outcome: 'fingerprint_mismatch',
-                reason: 'fingerprint_mismatch',
-                marker
-            };
-        }
-        return {
-            outcome: 'valid',
-            marker
-        };
+        return validateIndexCompletionProof({
+            codebasePath,
+            runtimeFingerprint: this.runtimeFingerprint,
+            getIndexCompletionMarker: typeof this.context.getIndexCompletionMarker === 'function'
+                ? (markerPath) => this.context.getIndexCompletionMarker(markerPath)
+                : undefined,
+            onProbeError: (error) => {
+                console.warn(`[INDEX-PROOF] Completion marker probe failed for '${codebasePath}': ${formatUnknownError(error)}`);
+            }
+        });
     }
     isPathWithinCodebase(targetPath, rootPath) {
         return targetPath === rootPath || targetPath.startsWith(`${rootPath}${path.sep}`);
@@ -933,6 +850,25 @@ export class ToolHandlers {
         }
         return normalized;
     }
+    trimTrailingSeparators(inputPath) {
+        const parsedRoot = path.parse(inputPath).root;
+        if (inputPath === parsedRoot) {
+            return inputPath;
+        }
+        return inputPath.replace(/[\\/]+$/, '');
+    }
+    canonicalizeCodebasePath(codebasePath) {
+        const resolved = path.resolve(codebasePath);
+        try {
+            const realPath = typeof fs.realpathSync.native === 'function'
+                ? fs.realpathSync.native(resolved)
+                : fs.realpathSync(resolved);
+            return this.trimTrailingSeparators(path.normalize(realPath));
+        }
+        catch {
+            return this.trimTrailingSeparators(path.normalize(resolved));
+        }
+    }
     loadRootGitignoreMatcher(codebaseRoot) {
         const cacheKey = this.canonicalizeCodebasePath(codebaseRoot);
         const gitignorePath = path.join(cacheKey, '.gitignore');
@@ -2302,17 +2238,23 @@ Agent instructions:
             console.warn(`[FORCE-REINDEX] Failed to list cloud collections while preparing cleanup: ${formatUnknownError(error)}`);
         }
         const droppedCollections = [];
+        const dropErrors = [];
         for (const candidateName of candidateNames) {
             try {
-                if (await vectorDb.hasCollection(candidateName)) {
-                    await vectorDb.dropCollection(candidateName);
+                const result = await deleteCollectionWithVerification(vectorDb, candidateName);
+                if (result.attempts > 0) {
                     droppedCollections.push(candidateName);
                 }
             }
             catch (error) {
-                console.warn(`[FORCE-REINDEX] Failed to drop collection '${candidateName}': ${formatUnknownError(error)}`);
+                const message = formatUnknownError(error);
+                dropErrors.push(`${candidateName}: ${message}`);
+                console.warn(`[FORCE-REINDEX] Failed to drop collection '${candidateName}': ${message}`);
             }
         }
+        if (dropErrors.length > 0) {
+            throw new Error(`Force reindex cleanup failed before local state changes: ${dropErrors.join('; ')}`);
+        }
         // Ensure local Merkle/snapshot state is cleared for this codebase.
         try {
             await this.context.clearIndex(codebasePath);
@@ -2335,9 +2277,12 @@ Agent instructions:
             throw new Error(`Collection '${trimmedName}' does not exist in the connected Zilliz cluster.`);
         }
         const droppedCodebasePath = await this.resolveCollectionCodebasePath(vectorDb, trimmedName, new Map());
-        await vectorDb.dropCollection(trimmedName);
+        await deleteCollectionWithVerification(vectorDb, trimmedName);
         if (droppedCodebasePath) {
             this.snapshotManager.removeCodebaseCompletely(droppedCodebasePath);
+            if (typeof this.snapshotManager.markCodebaseCleared === 'function') {
+                this.snapshotManager.markCodebaseCleared(droppedCodebasePath, trimmedName);
+            }
             this.snapshotManager.saveCodebaseSnapshot();
             try {
                 await this.unwatchCodebase(droppedCodebasePath);
@@ -2366,7 +2311,7 @@ Agent instructions:
                 console.log(`[SYNC-CLOUD] ✅ No collections found in cloud (non-destructive reconcile keeps local snapshot unchanged)`);
                 return;
             }
-            const cloudCodebases = new Set();
+            const cloudCodebaseCollections = new Map();
             // Check each collection for codebase path
             for (const collectionName of collections) {
                 try {
@@ -2390,7 +2335,9 @@ Agent instructions:
                                 const codebasePath = metadata.codebasePath;
                                 if (codebasePath && typeof codebasePath === 'string') {
                                     console.log(`[SYNC-CLOUD] 📍 Found codebase path: ${codebasePath} in collection: ${collectionName}`);
-                                    cloudCodebases.add(codebasePath);
+                                    const collectionNames = cloudCodebaseCollections.get(codebasePath) ?? new Set();
+                                    collectionNames.add(collectionName);
+                                    cloudCodebaseCollections.set(codebasePath, collectionNames);
                                 }
                                 else {
                                     console.warn(`[SYNC-CLOUD] ⚠️  No codebasePath found in metadata for collection: ${collectionName}`);
@@ -2413,9 +2360,17 @@ Agent instructions:
                     // Continue with next collection
                 }
             }
-            console.log(`[SYNC-CLOUD] 📊 Found ${cloudCodebases.size} valid codebases in cloud`);
+            console.log(`[SYNC-CLOUD] 📊 Found ${cloudCodebaseCollections.size} valid codebases in cloud`);
             let hasChanges = false;
-            for (const cloudCodebasePath of cloudCodebases) {
+            for (const [cloudCodebasePath, collectionNames] of cloudCodebaseCollections.entries()) {
+                const activeCollectionNames = Array.from(collectionNames)
+                    .filter((collectionName) => (typeof this.snapshotManager.isCodebaseCleared !== 'function'
+                    || !this.snapshotManager.isCodebaseCleared(cloudCodebasePath, collectionName)));
+                if (typeof this.snapshotManager.isCodebaseCleared === 'function'
+                    && activeCollectionNames.length === 0) {
+                    console.log(`[SYNC-CLOUD] ⏭️  Skipping repair for intentionally cleared root '${cloudCodebasePath}'`);
+                    continue;
+                }
                 const localInfo = this.snapshotManager.getCodebaseInfo(cloudCodebasePath);
                 if (localInfo?.status === 'indexing') {
                     console.log(`[SYNC-CLOUD] ⏸️  Skipping repair for indexing root '${cloudCodebasePath}'`);
@@ -2524,15 +2479,15 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             // If force reindex, always clear every previous collection for this codebase hash.
             if (forceReindex) {
                 console.log(`[FORCE-REINDEX] 🔄 Preparing force cleanup for '${absolutePath}'`);
+                const droppedCollections = await this.clearAllCollectionsForForceReindex(absolutePath);
                 this.snapshotManager.removeCodebaseCompletely(absolutePath);
                 this.snapshotManager.saveCodebaseSnapshot();
                 try {
                     await this.unwatchCodebase(absolutePath);
                 }
                 catch {
-                    // Best-effort watcher cleanup before force rebuild.
+                    // Best-effort watcher cleanup after successful force cleanup.
                 }
-                const droppedCollections = await this.clearAllCollectionsForForceReindex(absolutePath);
                 if (droppedCollections.length > 0) {
                     const sortedDroppedCollections = [...droppedCollections].sort();
                     dropSummaryLine += `\nForce reindex cleanup dropped ${sortedDroppedCollections.length} prior collection(s) for this codebase hash: ${sortedDroppedCollections.join(', ')}.`;
@@ -2549,7 +2504,25 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                 if (requestedDropCollection === targetCollectionName) {
                     return this.manageResponse(manageAction, absolutePath, "error", `Error: zillizDropCollection cannot target '${targetCollectionName}' for this same codebase create flow. Use {"action":"create","path":"${absolutePath}","force":true} for reindexing this codebase.`, preflightOptions);
                 }
-                const dropResult = await this.dropZillizCollectionForCreate(requestedDropCollection);
+                let dropResult;
+                try {
+                    dropResult = await this.dropZillizCollectionForCreate(requestedDropCollection);
+                }
+                catch (error) {
+                    if (error instanceof RemoteCollectionDeletePendingError) {
+                        return this.manageResponse(manageAction, absolutePath, "error", `Zilliz collection '${requestedDropCollection}' remote deletion is still pending. Local index state was not changed. Retry after the backend has converged. Details: ${formatUnknownError(error)}`, {
+                            ...preflightOptions,
+                            reason: "remote_delete_pending",
+                            hints: {
+                                retry: {
+                                    tool: "manage_index",
+                                    args: { action: manageAction, path: absolutePath, zillizDropCollection: requestedDropCollection }
+                                }
+                            }
+                        });
+                    }
+                    throw error;
+                }
                 dropSummaryLine += dropResult.droppedCodebasePath
                     ? `\nDropped Zilliz collection '${requestedDropCollection}' (mapped codebase: '${dropResult.droppedCodebasePath}').`
                     : `\nDropped Zilliz collection '${requestedDropCollection}'.`;
@@ -2572,8 +2545,36 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     const guidanceMessage = await this.buildCollectionLimitMessage(absolutePath);
                     return this.manageResponse(manageAction, absolutePath, "error", guidanceMessage, preflightOptions);
                 }
+                if (validationError instanceof RemoteCollectionDeletePendingError) {
+                    return this.manageResponse(manageAction, absolutePath, "error", `Zilliz/Milvus validation collection deletion is still pending. Local index state was not changed. Retry after the backend has converged. Details: ${formatUnknownError(validationError)}`, {
+                        ...preflightOptions,
+                        reason: "remote_delete_pending",
+                        hints: {
+                            retry: {
+                                tool: "manage_index",
+                                args: { action: manageAction, path: absolutePath }
+                            }
+                        }
+                    });
+                }
                 const validationMessage = formatUnknownError(validationError);
-                return this.manageResponse(manageAction, absolutePath, "error", `Error validating collection creation: ${validationMessage}`, preflightOptions);
+                const backendTimeout = isBackendTimeoutError(validationError);
+                const timeoutOptions = backendTimeout
+                    ? {
+                        ...preflightOptions,
+                        reason: "backend_timeout",
+                        hints: {
+                            retry: {
+                                tool: "manage_index",
+                                args: { action: manageAction, path: absolutePath }
+                            }
+                        }
+                    }
+                    : preflightOptions;
+                const validationText = backendTimeout
+                    ? `Backend timeout while validating Zilliz/Milvus collection creation for '${absolutePath}'. The repo path is valid and local index state was not changed. This is retryable/operator-actionable: check backend availability or network latency, then retry manage_index action='${manageAction}'. Details: ${validationMessage}`
+                    : `Error validating collection creation: ${validationMessage}`;
+                return this.manageResponse(manageAction, absolutePath, "error", validationText, timeoutOptions);
             }
             // Add custom extensions if provided
             if (customFileExtensions.length > 0) {
@@ -4004,12 +4005,26 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                 console.log(`[CLEAR] Successfully cleared index for: ${absolutePath}`);
             }
             catch (error) {
+                if (error instanceof RemoteCollectionDeletePendingError) {
+                    const errorMsg = `Remote deletion is still pending for ${absolutePath}. Local index state was not changed. Details: ${formatUnknownError(error)}`;
+                    console.error(`[CLEAR] ${errorMsg}`);
+                    return this.manageResponse("clear", absolutePath, "error", errorMsg, {
+                        reason: "remote_delete_pending",
+                        hints: {
+                            retry: this.buildStatusHint(absolutePath),
+                            clear: { tool: "manage_index", args: { action: "clear", path: absolutePath } }
+                        }
+                    });
+                }
                 const errorMsg = `Failed to clear ${absolutePath}: ${error.message}`;
                 console.error(`[CLEAR] ${errorMsg}`);
                 return this.manageResponse("clear", absolutePath, "error", errorMsg);
             }
             // Completely remove the cleared codebase from snapshot
             this.snapshotManager.removeCodebaseCompletely(absolutePath);
+            if (typeof this.snapshotManager.markCodebaseCleared === 'function') {
+                this.snapshotManager.markCodebaseCleared(absolutePath, this.context.resolveCollectionName(absolutePath));
+            }
             // Reset indexing stats if this was the active codebase
             this.indexingStats = null;
             // Save snapshot after clearing index

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 ManageIndexStatus = "ok" | "not_ready" | "not_indexed" | "requires_reindex" | "blocked" | "error";
-export type ManageIndexReason = "indexing" | "not_indexed" | "requires_reindex" | "unnecessary_reindex_ignore_only" | "preflight_unknown";
+export type ManageIndexReason = "indexing" | "not_indexed" | "requires_reindex" | "unnecessary_reindex_ignore_only" | "preflight_unknown" | "backend_timeout" | "remote_delete_pending";
 export type ManageReindexPreflightOutcome = "reindex_required" | "reindex_unnecessary_ignore_only" | "unknown" | "probe_failed";
 export interface ManageIndexToolHint {
     tool: "manage_index";

package/dist/core/snapshot.d.ts

@@ -16,7 +16,9 @@ export declare class SnapshotManager {
     private indexingCodebases;
     private codebaseFileCount;
     private codebaseInfoMap;
+    private clearTombstones;
     private pendingRemovals;
+    private pendingTombstoneRemovals;
     private isDirty;
     private runtimeFingerprint;
     constructor(runtimeFingerprint: IndexFingerprint);
@@ -41,16 +43,21 @@ export declare class SnapshotManager {
     private releaseSnapshotLock;
     private isValidIndexFingerprint;
     private isValidCodebaseInfoShape;
+    private isValidClearTombstoneShape;
     private toCodebaseInfo;
     private mapFromV1Snapshot;
     private mapFromV2Snapshot;
     private mapFromV3Snapshot;
+    private tombstoneMapFromV3Snapshot;
     private mapToCodebaseRecord;
+    private mapToTombstoneRecord;
     private codebaseRecordsEqual;
     private codebaseRecordEqualsUnknown;
     private canonicalizeUnknownRecord;
     private readCodebaseMapFromDisk;
+    private readTombstoneMapFromDisk;
     private mergeWithPersistedSnapshot;
+    private mergeTombstonesWithPersistedSnapshot;
     private loadV1Format;
     private loadV2Format;
     private loadV3Format;
@@ -67,6 +74,8 @@ export declare class SnapshotManager {
         path: string;
         info: CodebaseInfo;
     }>;
+    markCodebaseCleared(codebasePath: string, collectionName?: string): void;
+    isCodebaseCleared(codebasePath: string, collectionName?: string): boolean;
     getFailedCodebases(): string[];
     getCodebasesRequiringReindex(): string[];
     setCodebaseIndexing(codebasePath: string, progress?: number): void;

package/dist/core/snapshot.js

@@ -56,7 +56,9 @@ export class SnapshotManager {
         this.indexingCodebases = new Map();
         this.codebaseFileCount = new Map();
         this.codebaseInfoMap = new Map();
+        this.clearTombstones = new Map();
         this.pendingRemovals = new Set();
+        this.pendingTombstoneRemovals = new Set();
         this.isDirty = false;
         this.runtimeFingerprint = runtimeFingerprint;
         this.snapshotFilePath = path.join(os.homedir(), '.satori', 'mcp-codebase-snapshot.json');
@@ -110,6 +112,8 @@ export class SnapshotManager {
     }
     markCodebasePresent(codebasePath) {
         this.pendingRemovals.delete(codebasePath);
+        this.clearTombstones.delete(codebasePath);
+        this.pendingTombstoneRemovals.add(codebasePath);
     }
     markDirty() {
         this.isDirty = true;
@@ -356,6 +360,12 @@ export class SnapshotManager {
                 return false;
         }
     }
+    isValidClearTombstoneShape(value) {
+        return isRecord(value)
+            && typeof value.clearedAt === "string"
+            && !Number.isNaN(Date.parse(value.clearedAt))
+            && (value.collectionName === undefined || typeof value.collectionName === "string");
+    }
     toCodebaseInfo(rawInfo, sourceLabel, codebasePath) {
         if (!this.isValidCodebaseInfoShape(rawInfo)) {
             console.warn(`[SNAPSHOT] Skipping malformed ${sourceLabel} entry for '${codebasePath}'`);
@@ -413,6 +423,20 @@ export class SnapshotManager {
         }
         return map;
     }
+    tombstoneMapFromV3Snapshot(snapshot) {
+        const map = new Map();
+        if (!isRecord(snapshot.clearTombstones)) {
+            return map;
+        }
+        for (const [codebasePath, rawTombstone] of Object.entries(snapshot.clearTombstones)) {
+            if (!this.isValidClearTombstoneShape(rawTombstone)) {
+                console.warn(`[SNAPSHOT] Skipping malformed clear tombstone for '${codebasePath}'`);
+                continue;
+            }
+            map.set(codebasePath, rawTombstone);
+        }
+        return map;
+    }
     mapToCodebaseRecord(map) {
         const entries = Array.from(map.entries()).sort(([a], [b]) => a.localeCompare(b));
         const codebases = {};
@@ -421,6 +445,17 @@ export class SnapshotManager {
         }
         return codebases;
     }
+    mapToTombstoneRecord(map) {
+        if (map.size === 0) {
+            return undefined;
+        }
+        const entries = Array.from(map.entries()).sort(([a], [b]) => a.localeCompare(b));
+        const tombstones = {};
+        for (const [codebasePath, tombstone] of entries) {
+            tombstones[codebasePath] = tombstone;
+        }
+        return tombstones;
+    }
     codebaseRecordsEqual(left, right) {
         return stableSerialize(left) === stableSerialize(right);
     }
@@ -457,6 +492,22 @@ export class SnapshotManager {
             return new Map();
         }
     }
+    readTombstoneMapFromDisk() {
+        if (!fs.existsSync(this.snapshotFilePath)) {
+            return new Map();
+        }
+        try {
+            const snapshotData = fs.readFileSync(this.snapshotFilePath, "utf8");
+            const snapshot = JSON.parse(snapshotData);
+            if (this.isV3Format(snapshot)) {
+                return this.tombstoneMapFromV3Snapshot(snapshot);
+            }
+        }
+        catch (error) {
+            console.warn("[SNAPSHOT] Unable to read persisted clear tombstones for merge:", error?.message || error);
+        }
+        return new Map();
+    }
     mergeWithPersistedSnapshot() {
         const merged = this.readCodebaseMapFromDisk();
         for (const removedPath of this.pendingRemovals) {
@@ -472,19 +523,32 @@ export class SnapshotManager {
         }
         return merged;
     }
+    mergeTombstonesWithPersistedSnapshot() {
+        const merged = this.readTombstoneMapFromDisk();
+        for (const removedPath of this.pendingTombstoneRemovals) {
+            merged.delete(removedPath);
+        }
+        for (const [codebasePath, tombstone] of this.clearTombstones.entries()) {
+            merged.set(codebasePath, tombstone);
+        }
+        return merged;
+    }
     loadV1Format(snapshot) {
         console.log('[SNAPSHOT] Loading v1 format snapshot');
         this.codebaseInfoMap = this.mapFromV1Snapshot(snapshot);
+        this.clearTombstones.clear();
         this.refreshDerivedState();
     }
     loadV2Format(snapshot) {
         console.log('[SNAPSHOT] Loading v2 format snapshot');
         this.codebaseInfoMap = this.mapFromV2Snapshot(snapshot);
+        this.clearTombstones.clear();
         this.refreshDerivedState();
     }
     loadV3Format(snapshot) {
         console.log('[SNAPSHOT] Loading v3 format snapshot');
         this.codebaseInfoMap = this.mapFromV3Snapshot(snapshot);
+        this.clearTombstones = this.tombstoneMapFromV3Snapshot(snapshot);
         this.refreshDerivedState();
     }
     quarantineCorruptSnapshot(error) {
@@ -522,6 +586,7 @@ export class SnapshotManager {
         console.log('[SNAPSHOT] Loading codebase snapshot from:', this.snapshotFilePath);
         try {
             this.pendingRemovals.clear();
+            this.pendingTombstoneRemovals.clear();
             this.isDirty = false;
             if (!fs.existsSync(this.snapshotFilePath)) {
                 console.log('[SNAPSHOT] Snapshot file does not exist. Starting with empty codebase list.');
@@ -547,6 +612,7 @@ export class SnapshotManager {
             else {
                 this.quarantineCorruptSnapshot(new Error('Snapshot format is malformed'));
                 this.codebaseInfoMap.clear();
+                this.clearTombstones.clear();
                 this.refreshDerivedState();
                 this.isDirty = false;
                 return;
@@ -559,13 +625,15 @@ export class SnapshotManager {
         catch (error) {
             this.quarantineCorruptSnapshot(error);
             this.codebaseInfoMap.clear();
+            this.clearTombstones.clear();
             this.pendingRemovals.clear();
+            this.pendingTombstoneRemovals.clear();
             this.refreshDerivedState();
             this.isDirty = false;
         }
     }
     saveCodebaseSnapshot(forceWrite = false) {
-        if (!forceWrite && !this.isDirty && this.pendingRemovals.size === 0) {
+        if (!forceWrite && !this.isDirty && this.pendingRemovals.size === 0 && this.pendingTombstoneRemovals.size === 0) {
             return;
         }
         let lockHandle = null;
@@ -581,17 +649,21 @@ export class SnapshotManager {
                 return;
             }
             const mergedCodebaseMap = this.mergeWithPersistedSnapshot();
+            const mergedTombstones = this.mergeTombstonesWithPersistedSnapshot();
             const codebases = this.mapToCodebaseRecord(mergedCodebaseMap);
             const snapshot = {
                 formatVersion: 'v3',
                 codebases,
+                clearTombstones: this.mapToTombstoneRecord(mergedTombstones),
                 lastUpdated: new Date().toISOString(),
             };
             tempSnapshotPath = `${this.snapshotFilePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
             fs.writeFileSync(tempSnapshotPath, JSON.stringify(snapshot, null, 2));
             fs.renameSync(tempSnapshotPath, this.snapshotFilePath);
             this.codebaseInfoMap = mergedCodebaseMap;
+            this.clearTombstones = mergedTombstones;
             this.pendingRemovals.clear();
+            this.pendingTombstoneRemovals.clear();
             this.isDirty = false;
             this.refreshDerivedState();
             console.log(`[SNAPSHOT] Snapshot saved in v3 format. Indexed: ${this.indexedCodebases.length}, Indexing: ${this.indexingCodebases.size}, Failed: ${this.getFailedCodebases().length}, RequiresReindex: ${this.getCodebasesRequiringReindex().length}`);
@@ -637,6 +709,25 @@ export class SnapshotManager {
     getAllCodebases() {
         return Array.from(this.codebaseInfoMap.entries()).map(([p, info]) => ({ path: p, info }));
     }
+    markCodebaseCleared(codebasePath, collectionName) {
+        this.removeCodebaseCompletely(codebasePath);
+        this.clearTombstones.set(codebasePath, {
+            clearedAt: new Date().toISOString(),
+            collectionName,
+        });
+        this.pendingTombstoneRemovals.delete(codebasePath);
+        this.markDirty();
+    }
+    isCodebaseCleared(codebasePath, collectionName) {
+        const tombstone = this.clearTombstones.get(codebasePath);
+        if (!tombstone) {
+            return false;
+        }
+        if (collectionName === undefined || tombstone.collectionName === undefined) {
+            return true;
+        }
+        return tombstone.collectionName === collectionName;
+    }
     getFailedCodebases() {
         return Array.from(this.codebaseInfoMap.entries())
             .filter(([_, info]) => info.status === 'indexfailed')

package/dist/embedding.js

@@ -3,7 +3,7 @@ import { OpenAIEmbedding, VoyageAIEmbedding, GeminiEmbedding, OllamaEmbedding }
 export function createEmbeddingInstance(config) {
     console.log(`[EMBEDDING] Creating ${config.encoderProvider} embedding instance...`);
     switch (config.encoderProvider) {
-        case 'OpenAI':
+        case 'OpenAI': {
             if (!config.openaiKey) {
                 console.error(`[EMBEDDING] ❌ OpenAI API key is required but not provided`);
                 throw new Error('OPENAI_API_KEY is required for OpenAI embedding provider');
@@ -16,7 +16,8 @@ export function createEmbeddingInstance(config) {
             });
             console.log(`[EMBEDDING] ✅ OpenAI embedding instance created successfully`);
             return openaiEmbedding;
-        case 'VoyageAI':
+        }
+        case 'VoyageAI': {
             if (!config.voyageKey) {
                 console.error(`[EMBEDDING] ❌ VoyageAI API key is required but not provided`);
                 throw new Error('VOYAGEAI_API_KEY is required for VoyageAI embedding provider');
@@ -32,7 +33,8 @@ export function createEmbeddingInstance(config) {
             });
             console.log(`[EMBEDDING] ✅ VoyageAI embedding instance created successfully`);
             return voyageEmbedding;
-        case 'Gemini':
+        }
+        case 'Gemini': {
             if (!config.geminiKey) {
                 console.error(`[EMBEDDING] ❌ Gemini API key is required but not provided`);
                 throw new Error('GEMINI_API_KEY is required for Gemini embedding provider');
@@ -45,7 +47,8 @@ export function createEmbeddingInstance(config) {
             });
             console.log(`[EMBEDDING] ✅ Gemini embedding instance created successfully`);
             return geminiEmbedding;
-        case 'Ollama':
+        }
+        case 'Ollama': {
             const ollamaEndpoint = config.ollamaEndpoint || 'http://127.0.0.1:11434';
             console.log(`[EMBEDDING] 🔧 Configuring Ollama with model: ${config.encoderModel}, host: ${ollamaEndpoint}`);
             const ollamaEmbedding = new OllamaEmbedding({
@@ -54,6 +57,7 @@ export function createEmbeddingInstance(config) {
             });
             console.log(`[EMBEDDING] ✅ Ollama embedding instance created successfully`);
             return ollamaEmbedding;
+        }
         default:
             console.error(`[EMBEDDING] ❌ Unsupported embedding provider: ${config.encoderProvider}`);
             throw new Error(`Unsupported embedding provider: ${config.encoderProvider}`);

package/dist/tools/list_codebases.js

@@ -1,94 +1,8 @@
-import fs from "node:fs";
-import path from "node:path";
 import { z } from "zod";
 import { formatZodError } from "./types.js";
+import { validateCompletionProof } from "../core/completion-proof.js";
 const listCodebasesInputSchema = z.object({}).strict();
 const comparePathAsc = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
-function trimTrailingSeparators(inputPath) {
-    const normalized = path.normalize(inputPath);
-    const parsedRoot = path.parse(normalized).root;
-    if (normalized === parsedRoot) {
-        return normalized;
-    }
-    return normalized.replace(/[\\/]+$/, "");
-}
-function canonicalizeCodebasePath(codebasePath) {
-    const resolved = path.resolve(codebasePath);
-    try {
-        const realPath = typeof fs.realpathSync.native === "function"
-            ? fs.realpathSync.native(resolved)
-            : fs.realpathSync(resolved);
-        return trimTrailingSeparators(path.normalize(realPath));
-    }
-    catch {
-        return trimTrailingSeparators(path.normalize(resolved));
-    }
-}
-function markerMatchesRuntimeFingerprint(marker, ctx) {
-    const runtimeFingerprint = ctx.runtimeFingerprint;
-    if (!runtimeFingerprint || typeof runtimeFingerprint !== "object") {
-        return true;
-    }
-    const fingerprint = marker?.fingerprint;
-    if (!fingerprint || typeof fingerprint !== "object") {
-        return false;
-    }
-    return fingerprint.embeddingProvider === runtimeFingerprint.embeddingProvider
-        && fingerprint.embeddingModel === runtimeFingerprint.embeddingModel
-        && Number(fingerprint.embeddingDimension) === Number(runtimeFingerprint.embeddingDimension)
-        && fingerprint.vectorStoreProvider === runtimeFingerprint.vectorStoreProvider
-        && fingerprint.schemaVersion === runtimeFingerprint.schemaVersion;
-}
-function validateMarkerShape(expectedCodebasePath, marker) {
-    if (!marker || typeof marker !== "object") {
-        return { ok: false, reason: "invalid_payload" };
-    }
-    if (marker.kind !== "satori_index_completion_v1") {
-        return { ok: false, reason: "invalid_marker_kind" };
-    }
-    if (typeof marker.codebasePath !== "string" || marker.codebasePath.trim().length === 0) {
-        return { ok: false, reason: "invalid_payload" };
-    }
-    if (!marker.fingerprint || typeof marker.fingerprint !== "object") {
-        return { ok: false, reason: "invalid_payload" };
-    }
-    if (!Number.isFinite(Number(marker.indexedFiles)) || !Number.isFinite(Number(marker.totalChunks))) {
-        return { ok: false, reason: "invalid_payload" };
-    }
-    if (typeof marker.completedAt !== "string" || Number.isNaN(Date.parse(marker.completedAt))) {
-        return { ok: false, reason: "invalid_payload" };
-    }
-    const expectedCanonical = canonicalizeCodebasePath(expectedCodebasePath);
-    const markerCanonical = canonicalizeCodebasePath(marker.codebasePath);
-    if (expectedCanonical !== markerCanonical) {
-        return { ok: false, reason: "path_mismatch" };
-    }
-    return { ok: true };
-}
-async function validateCompletionProof(codebasePath, ctx) {
-    const getMarker = ctx.context?.getIndexCompletionMarker;
-    if (typeof getMarker !== "function") {
-        return { outcome: "probe_failed", reason: "probe_failed" };
-    }
-    let marker;
-    try {
-        marker = await getMarker(codebasePath);
-    }
-    catch {
-        return { outcome: "probe_failed", reason: "probe_failed" };
-    }
-    if (!marker) {
-        return { outcome: "stale_local", reason: "missing_marker_doc" };
-    }
-    const markerShape = validateMarkerShape(codebasePath, marker);
-    if (!markerShape.ok) {
-        return { outcome: "stale_local", reason: markerShape.reason };
-    }
-    if (!markerMatchesRuntimeFingerprint(marker, ctx)) {
-        return { outcome: "fingerprint_mismatch", reason: "fingerprint_mismatch" };
-    }
-    return { outcome: "valid" };
-}
 export const listCodebasesTool = {
     name: "list_codebases",
     description: () => "List tracked codebases and their indexing state.",
@@ -121,7 +35,13 @@ export const listCodebasesTool = {
             .filter((e) => e.info.status === "indexed" || e.info.status === "sync_completed");
         const completionProofChecks = await Promise.all(readyCandidates.map(async (entry) => ({
             entry,
-            proof: await validateCompletionProof(entry.path, ctx)
+            proof: await validateCompletionProof({
+                codebasePath: entry.path,
+                runtimeFingerprint: ctx.runtimeFingerprint,
+                getIndexCompletionMarker: typeof ctx.context?.getIndexCompletionMarker === "function"
+                    ? (markerPath) => ctx.context.getIndexCompletionMarker(markerPath)
+                    : undefined
+            })
         })));
         const ready = [];
         const requiresReindex = all
@@ -147,7 +67,7 @@ export const listCodebasesTool = {
             }
             if (proof.outcome === "probe_failed") {
                 // Probe failure is non-authoritative: keep local ready status stable.
-                ready.push({ path: entry.path });
+                ready.push({ path: entry.path, probeFailed: true });
                 continue;
             }
             if (proof.outcome === "fingerprint_mismatch") {
@@ -168,7 +88,10 @@ export const listCodebasesTool = {
         if (byStatus.indexed.length > 0) {
             lines.push('### Ready');
             for (const item of byStatus.indexed) {
-                lines.push(`- \`${item.path}\``);
+                const suffix = item.probeFailed
+                    ? " (completion proof probe failed; verify with manage_index action='status')"
+                    : "";
+                lines.push(`- \`${item.path}\`${suffix}`);
             }
             lines.push('');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-mcp",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "description": "MCP server for Satori with agent-safe semantic search and indexing",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,7 @@
     "ignore": "^7.0.5",
     "zod": "^3.25.55",
     "zod-to-json-schema": "^3.25.1",
-    "@zokizuan/satori-core": "1.3.0"
+    "@zokizuan/satori-core": "1.5.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",