@zokizuan/satori-mcp 4.11.16 → 4.11.17

package/README.md

@@ -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.16 --help
+npx -y @zokizuan/satori-mcp@4.11.17 --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.
@@ -73,10 +73,12 @@ Important defaults:
 - `read_file` only reads under tracked searchable roots (`indexed` / `sync_completed`); it is not a general host filesystem reader. Relative paths and root escapes are denied.
 - Prefer `recommendedNextAction` when present; if `callGraphHint.supported=false`, follow `navigationFallback` args rather than inventing spans.
 - `requires_reindex` means reindex first, then retry the original call (do not substitute `sync`).
-- `manage_index action="clear"` is destructive and should be explicit. `repair` only rebuilds local readiness when vector payload and trusted fingerprint proof match; otherwise use create/reindex.
+- `manage_index action="clear"` is destructive and should be explicit. `repair` reports structured proof across collection, snapshot, marker, fingerprint, payload, stale remote chunks, and navigation. Only no related collection routes to create; existing incompatible, incomplete, stale, malformed, or unprovable generations route to reindex. Backend failures preserve partial proof when available and should be diagnosed before retrying repair. Successful repair may write a fresh completion marker and rebuild navigation, but never re-embeds or rewrites source chunks.
 - After changing `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, embedding dimension, `HYBRID_MODE`, vector backend settings, or the Satori runtime version, restart **all** Satori MCP clients before running `manage_index create`, `reindex`, `sync`, `clear`, or `repair`.
 - Satori records live runtime owners in `~/.satori/runtime/owners.json` and blocks those index mutations with `status="blocked"` / `reason="runtime_owner_conflict"` if another live Satori MCP runtime has a different fingerprint, package version, or config identity.
 - On `runtime_owner_conflict`, the manage envelope lists conflicting **pids**, **versions**, and conflict reasons, plus a concrete `hints.nextStep`. MCP tools never kill other processes. Stop the listed host clients (or only orphaned Satori MCP node PIDs), leave a single package version/config running, then retry. `manage_index status` and `list_codebases` also show a compact **Runtime owners** line (live pids/versions); multi-version means mutations may block. `satori-cli doctor` reports multi-version live owners.
+- A separate canonical-root mutation lease permits multiple readers but only one create/reindex/sync/repair/clear writer across processes. Contention returns `reason="mutation_in_progress"`; `manage_index status` exposes `hints.activeMutation`. Leases do not have a time-based expiry, and a live owner is never evicted by age alone.
+- `zillizDropCollection` is fail-closed: Satori must prove the selected collection's owning codebase root and lease both affected roots before deletion. Unknown ownership or an active writer leaves the collection and local snapshot unchanged.
 - Grouped `search_codebase` results with supported call graph attach **`inboundRecovery`**: a ready-to-run `must:` search to verify callers before blast-radius edits (`call_graph` inbound stays advisory/low).
 
 ## Navigation Sidecars
@@ -136,7 +138,7 @@ 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/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.
+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. Repair responses may include optional `repairProof` evidence for collection, snapshot, marker, fingerprint, payload, staleRemoteChunks, and navigation. No related collection routes to create; an existing incompatible, incomplete, stale, malformed, or unprovable generation routes to reindex; backend failures preserve partial proof when collection began and should be diagnosed before retrying repair. Successful repair may write a fresh completion marker and rebuild navigation, but it does not re-embed or rewrite source chunks. 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). Successful sync responses include `syncStats` with `added`, `removed`, and `modified` counts; consume those fields instead of parsing `humanText`. create/reindex return the kickoff response immediately and do not poll to terminal state; use action="status" to observe progress. Status may include `languageCapabilities`, which combines declared claims with compatible symbol-registry and relationship-sidecar evidence for indexed languages. Mutation responses may include a durable `operation` receipt with `id`, canonical root, generation, accepted time, current phase, last durable transition, runtime fingerprint, and writer identity. Status returns the latest persisted receipt after restart. In a status envelope, top-level `action` remains `status` while `operation.action` names the observed mutation. Terminal phases are `completed`, `failed`, and `blocked`; `operation` is absent when no durable operation exists or contention was rejected before lease acquisition.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|

package/dist/config.d.ts

@@ -12,6 +12,23 @@ export interface IndexFingerprint {
     vectorStoreProvider: VectorStoreProvider;
     schemaVersion: 'dense_v3' | 'hybrid_v3';
 }
+export type IndexOperationAction = 'create' | 'reindex' | 'sync' | 'repair' | 'clear';
+export type IndexOperationPhase = 'accepted' | 'preflight' | 'scanning' | 'writing' | 'proving' | 'publishing' | 'completed' | 'failed' | 'blocked';
+export interface IndexOperationReceipt {
+    id: string;
+    action: IndexOperationAction;
+    canonicalRoot: string;
+    generation: number;
+    acceptedAt: string;
+    phase: IndexOperationPhase;
+    lastDurableTransitionAt: string;
+    runtimeFingerprint: IndexFingerprint;
+    writer: {
+        ownerId: string;
+        pid: number;
+        satoriVersion: string;
+    };
+}
 export interface ContextMcpConfig {
     name: string;
     version: string;
@@ -103,6 +120,7 @@ export interface CodebaseSnapshotV3 {
     formatVersion: 'v3';
     codebases: Record<string, CodebaseInfo>;
     clearTombstones?: Record<string, CodebaseClearTombstone>;
+    latestOperations?: Record<string, IndexOperationReceipt>;
     lastUpdated: string;
 }
 export type CodebaseSnapshot = CodebaseSnapshotV1 | CodebaseSnapshotV2 | CodebaseSnapshotV3;

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

@@ -107,8 +107,8 @@ export declare class CallGraphSidecarManager {
     });
     shouldRebuildForDelta(changedFiles: string[]): boolean;
     loadSidecar(codebasePath: string): CallGraphSidecar | null;
-    rebuildForCodebase(codebasePath: string, ignorePatterns?: string[]): Promise<CallGraphSidecarInfo>;
-    rebuildIfSupportedDelta(codebasePath: string, changedFiles: string[], ignorePatterns?: string[]): Promise<CallGraphSidecarInfo | null>;
+    rebuildForCodebase(codebasePath: string, ignorePatterns?: string[], assertMutationCurrent?: () => void): Promise<CallGraphSidecarInfo>;
+    rebuildIfSupportedDelta(codebasePath: string, changedFiles: string[], ignorePatterns?: string[], assertMutationCurrent?: () => void): Promise<CallGraphSidecarInfo | null>;
     queryGraph(codebasePath: string, symbolRef: CallGraphSymbolRef, options: {
         direction: CallGraphDirection;
         depth: number;

package/dist/core/call-graph.js

@@ -68,7 +68,7 @@ export class CallGraphSidecarManager {
             return null;
         }
     }
-    async rebuildForCodebase(codebasePath, ignorePatterns = []) {
+    async rebuildForCodebase(codebasePath, ignorePatterns = [], assertMutationCurrent) {
         const absoluteRoot = path.resolve(codebasePath);
         const files = await this.collectSourceFiles(absoluteRoot, ignorePatterns);
         const graph = await this.buildGraph(absoluteRoot, files);
@@ -83,7 +83,9 @@ export class CallGraphSidecarManager {
         };
         const sidecarPath = this.getSidecarPath(absoluteRoot);
         const sidecarDir = path.dirname(sidecarPath);
+        assertMutationCurrent?.();
         await fs.promises.mkdir(sidecarDir, { recursive: true });
+        assertMutationCurrent?.();
         await fs.promises.writeFile(sidecarPath, JSON.stringify(sidecar, null, 2), 'utf8');
         return {
             version: 'v3',
@@ -95,11 +97,11 @@ export class CallGraphSidecarManager {
             fingerprint: this.runtimeFingerprint,
         };
     }
-    async rebuildIfSupportedDelta(codebasePath, changedFiles, ignorePatterns = []) {
+    async rebuildIfSupportedDelta(codebasePath, changedFiles, ignorePatterns = [], assertMutationCurrent) {
         if (!this.shouldRebuildForDelta(changedFiles)) {
             return null;
         }
-        return this.rebuildForCodebase(codebasePath, ignorePatterns);
+        return this.rebuildForCodebase(codebasePath, ignorePatterns, assertMutationCurrent);
     }
     queryGraph(codebasePath, symbolRef, options) {
         const languageSupport = this.isSupportedQueryLanguage(symbolRef.file);

package/dist/core/current-source-symbols.d.ts

@@ -0,0 +1,15 @@
+import { type SymbolRecord } from "@zokizuan/satori-core";
+import type { PythonSourceBackedSpanRepair } from "./python-call-fallback.js";
+export type CurrentSourceSymbolValidation = PythonSourceBackedSpanRepair & {
+    match: "matched" | "missing" | "ambiguous" | "unavailable" | "not_applicable";
+};
+/**
+ * Rebuild exact-navigation identities from the current file using the same
+ * splitter and registry builder as indexing. Persisted IDs remain handles;
+ * only source-proven spans are substituted.
+ */
+export declare function validateCurrentSourceSymbolSpans(input: {
+    codebaseRoot: string;
+    symbols: SymbolRecord[];
+}): Promise<CurrentSourceSymbolValidation[]>;
+//# sourceMappingURL=current-source-symbols.d.ts.map

package/dist/core/current-source-symbols.js

@@ -0,0 +1,237 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { AstCodeSplitter, buildSymbolRecordsForFile, normalizeLanguageId, openRegularFileInsideRoot, } from "@zokizuan/satori-core";
+const CURRENT_SOURCE_LANGUAGES = new Set(["typescript", "javascript", "python"]);
+const CURRENT_SOURCE_MAX_BYTES = 256 * 1024;
+function isInsideRoot(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+async function readCurrentSource(codebaseRoot, relativeFile) {
+    let handle;
+    try {
+        const canonicalRoot = await fs.realpath(codebaseRoot);
+        const logicalFile = path.resolve(canonicalRoot, relativeFile);
+        if (!isInsideRoot(logicalFile, canonicalRoot)) {
+            return undefined;
+        }
+        handle = await openRegularFileInsideRoot(logicalFile, canonicalRoot);
+        const stat = await handle.stat();
+        if (stat.size > CURRENT_SOURCE_MAX_BYTES) {
+            return undefined;
+        }
+        const buffer = Buffer.allocUnsafe(CURRENT_SOURCE_MAX_BYTES + 1);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        if (offset > CURRENT_SOURCE_MAX_BYTES) {
+            return undefined;
+        }
+        return buffer.subarray(0, offset).toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function unchangedValidation(symbol, match) {
+    return {
+        symbol,
+        attempted: match !== "not_applicable",
+        validated: match === "matched",
+        repaired: false,
+        startBeforeDefinition: false,
+        endTruncated: false,
+        match,
+    };
+}
+function currentDeclarationKey(symbol) {
+    const span = symbol.span;
+    if (span.endByte !== undefined) {
+        // Export/decorator wrapper nodes and their declaration node share the
+        // same end boundary. Distinct same-line declarations do not.
+        return `${symbol.symbolKey}\0endByte:${span.endByte}`;
+    }
+    return [
+        symbol.symbolKey,
+        span.endLine,
+        span.endColumn ?? "",
+    ].join("\0");
+}
+function minOptional(left, right) {
+    if (left === undefined)
+        return right;
+    if (right === undefined)
+        return left;
+    return Math.min(left, right);
+}
+function maxOptional(left, right) {
+    if (left === undefined)
+        return right;
+    if (right === undefined)
+        return left;
+    return Math.max(left, right);
+}
+function compareOptionalPosition(left, right) {
+    if (left === right)
+        return 0;
+    if (left === undefined)
+        return 1;
+    if (right === undefined)
+        return -1;
+    return left - right;
+}
+function compareSourcePosition(left, right) {
+    return left.span.startLine - right.span.startLine
+        || compareOptionalPosition(left.span.startByte, right.span.startByte)
+        || compareOptionalPosition(left.span.startColumn, right.span.startColumn)
+        || left.span.endLine - right.span.endLine
+        || compareOptionalPosition(left.span.endByte, right.span.endByte)
+        || compareOptionalPosition(left.span.endColumn, right.span.endColumn);
+}
+function hasDistinctSourcePositions(symbols) {
+    return symbols.every((symbol, index) => index === 0 || compareSourcePosition(symbols[index - 1], symbol) !== 0);
+}
+/**
+ * Rebuild exact-navigation identities from the current file using the same
+ * splitter and registry builder as indexing. Persisted IDs remain handles;
+ * only source-proven spans are substituted.
+ */
+export async function validateCurrentSourceSymbolSpans(input) {
+    if (input.symbols.length === 0) {
+        return [];
+    }
+    const language = normalizeLanguageId(input.symbols[0].language);
+    if (!CURRENT_SOURCE_LANGUAGES.has(language)) {
+        return input.symbols.map((symbol) => unchangedValidation(symbol, "not_applicable"));
+    }
+    const relativeFile = input.symbols[0].file;
+    if (input.symbols.some((symbol) => symbol.file !== relativeFile || normalizeLanguageId(symbol.language) !== language)) {
+        return input.symbols.map((symbol) => unchangedValidation(symbol, "unavailable"));
+    }
+    const source = await readCurrentSource(input.codebaseRoot, relativeFile);
+    if (source === undefined) {
+        return input.symbols.map((symbol) => unchangedValidation(symbol, "unavailable"));
+    }
+    try {
+        const splitter = new AstCodeSplitter(Number.MAX_SAFE_INTEGER);
+        splitter.setChunkOverlap(0);
+        const split = await splitter.splitWithEvidence(source, language, relativeFile);
+        if (!split.structuralParseCompleted) {
+            return input.symbols.map((symbol) => unchangedValidation(symbol, "unavailable"));
+        }
+        const chunks = split.chunks;
+        const fileHash = crypto.createHash("sha256").update(source, "utf8").digest("hex");
+        const extractorVersion = input.symbols[0].extractorVersion;
+        const currentByIdentityAndSpan = new Map();
+        const currentFileOwner = buildSymbolRecordsForFile({
+            relativePath: relativeFile,
+            language,
+            content: source,
+            fileHash,
+            extractorVersion,
+            chunks: [],
+        })[0];
+        if (currentFileOwner) {
+            currentByIdentityAndSpan.set(currentDeclarationKey(currentFileOwner), currentFileOwner);
+        }
+        for (const chunk of chunks) {
+            const chunkSymbols = buildSymbolRecordsForFile({
+                relativePath: relativeFile,
+                language,
+                content: source,
+                fileHash,
+                extractorVersion,
+                chunks: [chunk],
+            });
+            for (const current of chunkSymbols.filter((symbol) => symbol.kind !== "file")) {
+                const declarationKey = currentDeclarationKey(current);
+                const existing = currentByIdentityAndSpan.get(declarationKey);
+                if (!existing) {
+                    currentByIdentityAndSpan.set(declarationKey, current);
+                    continue;
+                }
+                currentByIdentityAndSpan.set(declarationKey, {
+                    ...existing,
+                    span: {
+                        ...existing.span,
+                        startLine: Math.min(existing.span.startLine, current.span.startLine),
+                        endLine: Math.max(existing.span.endLine, current.span.endLine),
+                        startByte: minOptional(existing.span.startByte, current.span.startByte),
+                        endByte: maxOptional(existing.span.endByte, current.span.endByte),
+                        startColumn: minOptional(existing.span.startColumn, current.span.startColumn),
+                        endColumn: maxOptional(existing.span.endColumn, current.span.endColumn),
+                    },
+                });
+            }
+        }
+        const currentSymbols = [...currentByIdentityAndSpan.values()];
+        const currentByKey = new Map();
+        for (const current of currentSymbols) {
+            const matches = currentByKey.get(current.symbolKey) || [];
+            matches.push(current);
+            currentByKey.set(current.symbolKey, matches);
+        }
+        const persistedByKey = new Map();
+        for (const symbol of input.symbols) {
+            const matches = persistedByKey.get(symbol.symbolKey) || [];
+            matches.push(symbol);
+            persistedByKey.set(symbol.symbolKey, matches);
+        }
+        const assignedCurrentByPersistedId = new Map();
+        for (const [symbolKey, persisted] of persistedByKey) {
+            const current = currentByKey.get(symbolKey) || [];
+            if (persisted.length !== current.length) {
+                continue;
+            }
+            if (persisted.length > 1 && persisted.some((symbol) => symbol.fileHash !== fileHash)) {
+                continue;
+            }
+            const sortedPersisted = [...persisted].sort(compareSourcePosition);
+            const sortedCurrent = [...current].sort(compareSourcePosition);
+            if (persisted.length > 1
+                && (!hasDistinctSourcePositions(sortedPersisted) || !hasDistinctSourcePositions(sortedCurrent))) {
+                continue;
+            }
+            for (let index = 0; index < sortedPersisted.length; index += 1) {
+                assignedCurrentByPersistedId.set(sortedPersisted[index].symbolInstanceId, sortedCurrent[index]);
+            }
+        }
+        return input.symbols.map((symbol) => {
+            const matches = currentByKey.get(symbol.symbolKey) || [];
+            if (matches.length === 0) {
+                return unchangedValidation(symbol, "missing");
+            }
+            const current = assignedCurrentByPersistedId.get(symbol.symbolInstanceId);
+            if (!current) {
+                return unchangedValidation(symbol, "ambiguous");
+            }
+            const repaired = current.span.startLine !== symbol.span.startLine
+                || current.span.endLine !== symbol.span.endLine
+                || current.span.startByte !== symbol.span.startByte
+                || current.span.endByte !== symbol.span.endByte
+                || current.span.startColumn !== symbol.span.startColumn
+                || current.span.endColumn !== symbol.span.endColumn;
+            return {
+                symbol: repaired ? { ...symbol, span: current.span } : symbol,
+                attempted: true,
+                validated: true,
+                repaired,
+                startBeforeDefinition: symbol.span.startLine < current.span.startLine,
+                endTruncated: symbol.span.endLine < current.span.endLine,
+                match: "matched",
+            };
+        });
+    }
+    catch {
+        return input.symbols.map((symbol) => unchangedValidation(symbol, "unavailable"));
+    }
+}
+//# sourceMappingURL=current-source-symbols.js.map

package/dist/core/handlers.d.ts

@@ -8,6 +8,7 @@ import { CallGraphSidecarManager } from "./call-graph.js";
 import { type ReindexPreflightResult } from "./working-tree-state.js";
 import { type SearchDiagnostics } from "./search-execution.js";
 import { type RuntimeOwnerMutationGate } from "./runtime-owner.js";
+import { MutationLeaseCoordinator } from "./mutation-lease.js";
 type IndexCodebaseArgs = {
     path: string;
     force?: boolean;
@@ -26,6 +27,7 @@ type ReindexCodebaseArgs = {
 type ToolArgs = Record<string, unknown>;
 export declare class ToolHandlers {
     private readonly runtimeOwnerGate;
+    private readonly mutationLeaseCoordinator;
     private context;
     private snapshotManager;
     private syncManager;
@@ -48,7 +50,7 @@ export declare class ToolHandlers {
     private readonly vectorBackendMaintenance;
     private readonly relationshipBackedCallGraph;
     private readonly toolResponseBuilders;
-    constructor(context: Context, snapshotManager: SnapshotManager, syncManager: SyncManager, runtimeFingerprint: IndexFingerprint, capabilities: CapabilityResolver, now?: () => number, callGraphManager?: CallGraphSidecarManager, reranker?: VoyageAIReranker | null, gitignoreForceReloadEveryN?: number, navigationStore?: NavigationStore, runtimeOwnerGate?: RuntimeOwnerMutationGate | null);
+    constructor(context: Context, snapshotManager: SnapshotManager, syncManager: SyncManager, runtimeFingerprint: IndexFingerprint, capabilities: CapabilityResolver, now?: () => number, callGraphManager?: CallGraphSidecarManager, reranker?: VoyageAIReranker | null, gitignoreForceReloadEveryN?: number, navigationStore?: NavigationStore, runtimeOwnerGate?: RuntimeOwnerMutationGate | null, mutationLeaseCoordinator?: MutationLeaseCoordinator | null);
     private setIndexingStats;
     private clearIndexingStats;
     private createSearchPhaseTimings;
@@ -94,7 +96,20 @@ export declare class ToolHandlers {
     private buildRuntimeOwnerConflictResponse;
     private buildIndexingMetadata;
     private isIndexingStateStale;
+    /**
+     * Recover abandoned `indexing` lifecycle rows.
+     *
+     * Wall-clock grace applies only before exclusive ownership is proven. When
+     * `existingLease` is held (or startup forces exclusive acquisition), recovery
+     * runs immediately because a live compliant writer cannot share the root.
+     */
     private recoverStaleIndexingStateIfNeeded;
+    /**
+     * Startup entry for interrupted-index recovery. Acquires a mutation lease per
+     * root, skips live writers, and reuses the fenced recovery path (no unfenced
+     * snapshot lifecycle publication).
+     */
+    recoverInterruptedIndexingAtStartup(): Promise<void>;
     private buildManageActionBlockedMessage;
     private getManageRetryAfterMs;
     private buildStaleLocalHint;
@@ -110,7 +125,6 @@ export declare class ToolHandlers {
     private isPathWithinCodebase;
     private getTrackedRootEntryForPath;
     private probeLocalSearchCollectionState;
-    private markCodebaseSearchStateMissing;
     private summarizeFingerprint;
     private fingerprintsEqual;
     private isRuntimeFingerprintMismatch;