@zokizuan/satori-mcp 4.11.13 → 4.11.17

package/README.md

@@ -4,7 +4,7 @@ Read-only MCP server for Satori. It gives coding agents six deterministic tools
 
 ## Install
 
-Use the CLI installer for normal setup:
+Installer ownership is **`@zokizuan/satori-cli` only** (this package serves MCP tools; it does not install client configs). Use the CLI installer for normal setup:
 
 ```bash
 npx -y @zokizuan/satori-cli@latest install --client all
@@ -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.13 --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.
@@ -63,16 +63,23 @@ read_file path="/absolute/path/to/repo/src/auth.ts" start_line=1 end_line=160
 
 Important defaults:
 
-- `search_codebase` starts with runtime code, grouped by symbol.
-- `search_codebase` runs freshness checks before returning results.
+- Public paths for tools are **absolute filesystem paths**. Relative paths are rejected (not CWD-resolved).
+- `search_codebase` starts with `scope=runtime`, `resultMode=grouped`, `groupBy=symbol`, `rankingMode=auto_changed_first`.
+- `search_codebase` is the sync-on-read freshness tool; other tools may gate compatibility but do not replace it.
 - Grouped search is symbol-owned: chunks are supporting evidence for an owner symbol, not the final navigation unit.
 - Exact symbol navigation uses `symbolInstanceId`. `symbolKey` is stable-ish candidate lookup only, not exact identity.
+- Ready/`indexed` means searchable-readable, not automatically symbol-rich. Check `manage_index status` `symbolQuality` or Ready-line `symbolQuality=…` before treating outline/graph as rich navigation evidence (`symbol_rich` \| `mixed` \| `symbol_sparse` \| `search_only` \| `unknown` — observed registry evidence, not a parser diagnosis).
 - Index profiles still honor `.satoriignore`, `.gitignore`, `satori.toml`, and the hard denylist for secrets, lockfiles, generated output, dependencies, binaries, bundles, logs, and database dumps.
-- `read_file` is bounded and can return continuation hints.
-- `requires_reindex` means reindex first, then retry the original call.
-- `manage_index action="clear"` is destructive and should be explicit.
-- 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`, or `clear`.
-- 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. MCP tools do not kill processes or ask interactive cleanup questions.
+- `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` 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
 
@@ -81,7 +88,7 @@ Completed full indexes write a derived symbol registry and relationship sidecar.
 - The symbol registry stores candidate owner keys, exact symbol instances, file-owner fallback symbols, and outline records used by grouped search, `file_outline`, and exact reads.
 - The relationship sidecar stores conservative `CALLS v0` edges plus TypeScript/JavaScript `IMPORTS`/`EXPORTS v0` edges with manifest compatibility gates.
 - Runtime navigation still serves canonical JSON sidecars by default. When the default shared runtime store is created at process startup, `SATORI_NAVIGATION_BACKEND=sqlite` can opt that shared store into SQLite-backed reads only after SQLite proves parity with the canonical JSON symbol registry and relationship sidecars. If canonical JSON is missing or incompatible, SQLite is not served as truth; if SQLite is missing, stale, incompatible, or parity-mismatched while JSON is compatible, runtime falls back to JSON with a warning. When the default shared runtime store is created with `SATORI_NAVIGATION_DUAL_READ=1`, JSON remains the serving backend and the runtime emits once-per-root parity mismatch warnings without changing the served result.
-- `CALLS v0` is heuristic/name-based. Same-file unique targets can be high confidence, cross-file name-only targets start low confidence, and ambiguous same-name targets are skipped.
+- `CALLS v0` is heuristic/name-based. Same-file unique targets can be high confidence; cross-file name-only targets start low and are upgraded when IMPORTS/EXPORTS evidence supports them, or when the imported file has a unique same-name target (class methods without top-level EXPORTS). Generic names like `push`/`get` stay suppressed without EXPORTS. Ambiguous same-name targets are skipped.
 - `IMPORTS`/`EXPORTS v0` records only resolvable relative module edges and unambiguous local export declarations. Package imports, unresolved paths, ambiguous exports, and multiline module syntax are skipped.
 - `call_graph` uses compatible relationship sidecars as the canonical source for symbol-owned traversal.
 - Successful incremental sync reuses changed-file symbol output, preserves unchanged registry state, and recomputes relationships against the merged registry without re-splitting unchanged files. If changed-file indexing stops early, navigation state is cleared instead of publishing a mixed generation.
@@ -103,7 +110,7 @@ Users who want literal values in a client config can replace the generated pass-
 ```toml
 [mcp_servers.satori.env]
 EMBEDDING_PROVIDER = "VoyageAI"
-EMBEDDING_MODEL = "voyage-4-large"
+EMBEDDING_MODEL = "voyage-code-3"
 EMBEDDING_OUTPUT_DIMENSION = "1024"
 VOYAGEAI_API_KEY = "pa-..."
 VOYAGEAI_RERANKER_MODEL = "rerank-2.5"
@@ -115,7 +122,7 @@ Cloud-quality setup:
 
 ```bash
 EMBEDDING_PROVIDER=VoyageAI
-EMBEDDING_MODEL=voyage-4-large
+EMBEDDING_MODEL=voyage-code-3
 EMBEDDING_OUTPUT_DIMENSION=1024
 VOYAGEAI_API_KEY=your-api-key
 VOYAGEAI_RERANKER_MODEL=rerank-2.5
@@ -131,12 +138,12 @@ 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 |
 |---|---|---|---|---|
 | `action` | enum("create", "reindex", "sync", "status", "clear", "repair") | yes |  | Required operation to run. |
-| `path` | string | yes |  | ABSOLUTE path to the target codebase. |
+| `path` | string | yes |  | ABSOLUTE filesystem path to the target codebase (relative paths are rejected). |
 | `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. |
 | `customExtensions` | array<string> | no |  | Only for action='create'. Additional file extensions to include. |
@@ -149,9 +156,9 @@ Unified semantic search with runtime-first defaults (start with scope="runtime")
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `path` | string | yes |  | ABSOLUTE path to an indexed codebase or subdirectory. |
+| `path` | string | yes |  | ABSOLUTE filesystem path to an indexed codebase or subdirectory (relative paths are rejected). |
 | `query` | string | yes |  | Natural-language query. |
-| `scope` | enum("runtime", "mixed", "docs") | no | `"runtime"` | Search scope policy. runtime includes source/runtime code and tests while excluding docs/generated/artifacts/landing/fixtures; docs returns docs/tests only; mixed includes all. Docs scope skips reranker by policy in the current tool surface. |
+| `scope` | enum("runtime", "mixed", "docs") | no | `"runtime"` | Search scope policy. runtime includes source/runtime code and tests while excluding docs/generated/artifacts/landing/fixtures; docs returns documentation paths only (not tests); mixed includes all. Docs scope skips reranker by policy in the current tool surface. |
 | `resultMode` | enum("grouped", "raw") | no | `"grouped"` | Output mode. grouped returns merged search groups, raw returns chunk hits. |
 | `groupBy` | enum("symbol", "file") | no | `"symbol"` | Grouping strategy in grouped mode. |
 | `rankingMode` | enum("default", "auto_changed_first") | no | `"auto_changed_first"` | Ranking policy. auto_changed_first boosts files changed in the current git working tree when available. |
@@ -160,11 +167,11 @@ Unified semantic search with runtime-first defaults (start with scope="runtime")
 
 ### `call_graph`
 
-Traverse registry-resolved caller/callee relationships for indexed TS/JS/Python code. On symbol-owned indexes, call_graph uses compatible relationship sidecars for conservative CALLS v0 traversal and upgrades low-confidence cross-file calls only when current IMPORTS/EXPORTS evidence deterministically supports the target symbol. In successful traversal responses, sidecar.nodeCount and sidecar.edgeCount report the counts returned in that response, not whole-sidecar totals for the indexed codebase.
+Traverse registry-resolved caller/callee relationships for indexed TS/JS/Python code. Relationship-backed CALLS v0 is heuristic and name-based (not a compiler-grade call graph): unique same-file name matches are high confidence; cross-file edges stay low unless IMPORTS/EXPORTS evidence upgrades them, or an imported module has a unique same-name target (e.g. class methods without a top-level EXPORTS record; generic names like push/get stay suppressed). Traversal is bounded (depth/limit) and incomplete by design—empty or short edge lists are not proof of “no callers.” Output is advisory navigation context, not authoritative blast-radius proof; confirm impact with search_codebase, read_file, tests, and references before editing. In successful traversal responses, sidecar.nodeCount and sidecar.edgeCount report counts returned in that response, not whole-sidecar totals.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `path` | string | yes |  | ABSOLUTE path to the indexed codebase root (or subdirectory). |
+| `path` | string | yes |  | ABSOLUTE filesystem path to the indexed codebase root or subdirectory (relative paths are rejected). |
 | `symbolRef` | object | yes |  | Symbol reference from a grouped search result callGraphHint. |
 | `direction` | enum("callers", "callees", "both") | no | `"both"` | Traversal direction from the starting symbol. |
 | `depth` | integer | no | `1` | Traversal depth (max 3). |
@@ -176,8 +183,8 @@ Return a sidecar-backed symbol outline for one file, including call_graph jump h
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `path` | string | yes |  | ABSOLUTE path to the indexed codebase root. |
-| `file` | string | yes |  | Relative file path inside the codebase root. |
+| `path` | string | yes |  | ABSOLUTE filesystem path to the indexed codebase root (relative paths are rejected). |
+| `file` | string | yes |  | Repo-relative file path inside the codebase root (not absolute; resolved only against that root). |
 | `start_line` | integer | no |  | Optional start line filter (1-based, inclusive). |
 | `end_line` | integer | no |  | Optional end line filter (1-based, inclusive). |
 | `limitSymbols` | integer | no | `500` | Maximum number of returned symbols after line filtering. |
@@ -187,11 +194,11 @@ Return a sidecar-backed symbol outline for one file, including call_graph jump h
 
 ### `read_file`
 
-Read file content from the local filesystem, with optional 1-based inclusive line ranges and safe truncation.
+Read file content under an indexed/searchable Satori codebase root only (not a general host filesystem reader). Requires an absolute path whose canonical real path is inside a tracked root with status indexed or sync_completed. Supports optional 1-based inclusive line ranges and safe truncation.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `path` | string | yes |  | ABSOLUTE path to the file. |
+| `path` | string | yes |  | ABSOLUTE path to the file under an indexed/searchable codebase root (relative paths are rejected). |
 | `start_line` | integer | no |  | Optional start line (1-based, inclusive). |
 | `end_line` | integer | no |  | Optional end line (1-based, inclusive). |
 | `mode` | enum("plain", "annotated") | no | `"plain"` | Output mode. plain returns text only; annotated returns content plus sidecar-backed outline metadata. |

package/dist/cli/args.d.ts

@@ -19,16 +19,6 @@ export type ParsedCommand = {
     kind: "help";
 } | {
     kind: "version";
-} | {
-    kind: "install";
-    client: InstallClient;
-    dryRun: boolean;
-    installGuidanceHook: boolean;
-    profile?: InstallProfile;
-} | {
-    kind: "uninstall";
-    client: InstallClient;
-    dryRun: boolean;
 } | {
     kind: "tools-list";
 } | {
@@ -49,8 +39,9 @@ export interface ResolveRawArgsOptions {
     stdin?: NodeJS.ReadStream;
     stdinTimeoutMs: number;
 }
-export type InstallClient = "all" | "claude" | "codex" | "opencode";
-export type InstallProfile = "default" | "minimal" | "all-text";
+/** Hard-deprecation messages only — no installer work, no config writes. */
+export declare const MCP_INSTALL_USE_SATORI_CLI_MESSAGE = "Install is owned by @zokizuan/satori-cli. Use: npx -y @zokizuan/satori-cli@latest install --client <client>";
+export declare const MCP_UNINSTALL_USE_SATORI_CLI_MESSAGE = "Uninstall is owned by @zokizuan/satori-cli. Use: npx -y @zokizuan/satori-cli@latest uninstall --client <client>";
 export declare function parseCliArgs(argv: string[]): ParsedCliInput;
 export declare function resolveRawArguments(rawArgsMode: RawArgsMode, options: ResolveRawArgsOptions): Promise<Record<string, unknown>>;
 export declare function parseWrapperArgumentsFromSchema(toolName: string, inputSchema: unknown, wrapperArgs: string[]): Record<string, unknown>;

package/dist/cli/args.js

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import { CliError } from "./errors.js";
+/** Installer SSOT is packages/cli (satori-cli). MCP CLI keeps these reserved so they never become tool wrappers. */
 const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version", "install", "uninstall"]);
+/** Hard-deprecation messages only — no installer work, no config writes. */
+export const MCP_INSTALL_USE_SATORI_CLI_MESSAGE = "Install is owned by @zokizuan/satori-cli. Use: npx -y @zokizuan/satori-cli@latest install --client <client>";
+export const MCP_UNINSTALL_USE_SATORI_CLI_MESSAGE = "Uninstall is owned by @zokizuan/satori-cli. Use: npx -y @zokizuan/satori-cli@latest uninstall --client <client>";
 const PRIMITIVE_TYPES = new Set(["string", "number", "integer", "boolean"]);
 function isWrapperJsonSchema(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -112,45 +116,6 @@ function parseRawArgsMode(args) {
     }
     return { rawArgsMode, remaining };
 }
-function parseInstallCommand(kind, args) {
-    let client = "all";
-    let dryRun = false;
-    let installGuidanceHook = false;
-    let profile;
-    for (let i = 0; i < args.length; i += 1) {
-        const token = args[i];
-        if (token === "--client") {
-            const next = args[i + 1];
-            if (next !== "all" && next !== "claude" && next !== "codex" && next !== "opencode") {
-                throw new CliError("E_USAGE", "--client must be one of: all, claude, codex, opencode.", 2);
-            }
-            client = next;
-            i += 1;
-            continue;
-        }
-        if (token === "--dry-run") {
-            dryRun = true;
-            continue;
-        }
-        if (kind === "install" && token === "--install-guidance-hook") {
-            installGuidanceHook = true;
-            continue;
-        }
-        if (kind === "install" && token === "--profile") {
-            const next = args[i + 1];
-            if (next !== "default" && next !== "minimal" && next !== "all-text") {
-                throw new CliError("E_USAGE", "--profile must be one of: default, minimal, all-text.", 2);
-            }
-            profile = next;
-            i += 1;
-            continue;
-        }
-        throw new CliError("E_USAGE", `Unknown arguments for ${kind}: ${args.slice(i).join(" ")}`, 2);
-    }
-    return kind === "install"
-        ? { kind, client, dryRun, installGuidanceHook, profile }
-        : { kind, client, dryRun };
-}
 export function parseCliArgs(argv) {
     const { globals, rest } = parseGlobalOptions(argv);
     if (rest.length === 0 || rest[0] === "help" || rest.includes("--help") || rest.includes("-h")) {
@@ -166,16 +131,10 @@ export function parseCliArgs(argv) {
         };
     }
     if (rest[0] === "install") {
-        return {
-            globals,
-            command: parseInstallCommand("install", rest.slice(1))
-        };
+        throw new CliError("E_USAGE", MCP_INSTALL_USE_SATORI_CLI_MESSAGE, 2);
     }
     if (rest[0] === "uninstall") {
-        return {
-            globals,
-            command: parseInstallCommand("uninstall", rest.slice(1))
-        };
+        throw new CliError("E_USAGE", MCP_UNINSTALL_USE_SATORI_CLI_MESSAGE, 2);
     }
     if (rest[0] === "tools") {
         if (rest.length === 2 && rest[1] === "list") {

package/dist/cli/index.d.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import { type CallToolResult, type ListToolsResult } from "./client.js";
-import { type ManagedRuntimeCommand } from "./install.js";
 interface RunCliOptions {
     writeStdout?: (text: string) => void;
     writeStderr?: (text: string) => void;
@@ -12,8 +11,6 @@ interface RunCliOptions {
     startupTimeoutMs?: number;
     callTimeoutMs?: number;
     cwd?: string;
-    installabilityVerifier?: () => string | Promise<string>;
-    installRuntimeCommand?: ManagedRuntimeCommand;
     connectSession?: (options: {
         command: string;
         args: string[];

package/dist/cli/index.js

@@ -6,8 +6,6 @@ import { parseCliArgs, parseWrapperArgumentsFromSchema, resolveRawArguments } fr
 import { connectCliMcpSession } from "./client.js";
 import { asCliError, CliError } from "./errors.js";
 import { emitError, emitJson, parseStructuredEnvelope } from "./format.js";
-import { executeInstallCommand } from "./install.js";
-import { verifyManagedPackageInstallability } from "./package-installability.js";
 import { resolveServerEntryPath } from "./resolve-server-entry.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null;
@@ -44,15 +42,14 @@ function resolveDefaultServerArgs() {
 }
 function buildHelpPayload() {
     return {
-        usage: "satori-cli <command>",
+        usage: "satori <command> (tool shell; install via satori-cli)",
         commands: [
-            "install [--client all|codex|claude|opencode] [--profile default|minimal|all-text] [--dry-run] [--install-guidance-hook]",
-            "uninstall [--client all|codex|claude|opencode] [--dry-run]",
             "tools list",
             "tool call <toolName> --args-json '<json>'",
             "tool call <toolName> --args-file <path>",
             "<toolName> [schema-driven flags]"
         ],
+        install: "npx -y @zokizuan/satori-cli@latest install --client all",
         globalFlags: [
             "--startup-timeout-ms <n>",
             "--call-timeout-ms <n>",
@@ -155,22 +152,6 @@ export async function runCli(argv, options = {}) {
             }
             return 0;
         }
-        if (parsed.command.kind === "install" || parsed.command.kind === "uninstall") {
-            let packageSpecifier;
-            if (parsed.command.kind === "install") {
-                packageSpecifier = await (options.installabilityVerifier || verifyManagedPackageInstallability)();
-            }
-            const result = executeInstallCommand(parsed.command, {
-                homeDir: effectiveEnv.HOME,
-                packageSpecifier,
-                runtimeCommand: options.installRuntimeCommand,
-            });
-            emitJson(writers, result);
-            if (parsed.globals.format === "text") {
-                writers.writeStderr(`satori-cli ${parsed.command.kind} completed for ${parsed.command.client}.\n`);
-            }
-            return 0;
-        }
         const session = await (options.connectSession || connectCliMcpSession)({
             command: options.serverCommand || process.execPath,
             args: options.serverArgs || resolveDefaultServerArgs(),

package/dist/config.d.ts

@@ -3,6 +3,8 @@ export type VectorStoreProvider = 'Milvus';
 export type FingerprintSource = 'verified' | 'assumed_v2';
 export declare const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 export declare const DEFAULT_MANAGE_RETRY_AFTER_MS = 2000;
+/** Package version from packages/mcp/package.json (not the stale historical default 1.0.0). */
+export declare function resolveMcpPackageVersion(): string;
 export interface IndexFingerprint {
     embeddingProvider: EmbeddingProvider;
     embeddingModel: string;
@@ -10,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;
@@ -101,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/config.js

@@ -1,13 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { envManager } from "@zokizuan/satori-core";
 export const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 export const DEFAULT_MANAGE_RETRY_AFTER_MS = 2000;
+/** Package version from packages/mcp/package.json (not the stale historical default 1.0.0). */
+export function resolveMcpPackageVersion() {
+    try {
+        const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const raw = fs.readFileSync(packageJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+            return parsed.version.trim();
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0";
+}
 // Helper function to get default model for each provider
 export function getDefaultModelForProvider(provider) {
     switch (provider) {
         case 'OpenAI':
             return 'text-embedding-3-small';
         case 'VoyageAI':
-            return 'voyage-4-large';
+            return 'voyage-code-3';
         case 'Gemini':
             return 'gemini-embedding-001';
         case 'Ollama':
@@ -106,7 +124,7 @@ export function createMcpConfig() {
     }
     const config = {
         name: envManager.get('MCP_SERVER_NAME') || "Satori MCP Server",
-        version: envManager.get('MCP_SERVER_VERSION') || "1.0.0",
+        version: envManager.get('MCP_SERVER_VERSION') || resolveMcpPackageVersion(),
         // Embedding provider configuration
         encoderProvider: defaultProvider,
         encoderModel: getEmbeddingModelForProvider(defaultProvider),
@@ -215,7 +233,7 @@ Examples:
   OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 satori
 
   # Start MCP server with VoyageAI and specific model
-  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token satori
+  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-code-3 MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token satori
 
   # Start MCP server with Gemini and specific model
   EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token satori

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

@@ -84,6 +84,8 @@ export interface CallGraphResponseSupported {
         nodeCount: number;
         edgeCount: number;
     };
+    /** Executable recovery steps when graph evidence is incomplete (e.g. notes-only inbound). */
+    hints?: Record<string, unknown>;
 }
 export type CallGraphQueryResponse = CallGraphResponseSupported | CallGraphResponseUnsupported;
 export interface CallGraphDeltaPolicy {
@@ -105,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