@zokizuan/satori-mcp 4.11.13 → 4.11.16

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.16 --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,21 @@ 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` only rebuilds local readiness when vector payload and trusted fingerprint proof match; otherwise use create/reindex.
+- 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.
+- 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 +86,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 +108,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 +120,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
@@ -136,7 +141,7 @@ Manage index lifecycle operations (create/reindex/sync/status/clear/repair) for
 | 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 +154,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 +165,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 +181,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 +192,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;

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 {

package/dist/core/handlers.d.ts

@@ -7,7 +7,7 @@ import { FileOutlineInput } from "./search-types.js";
 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 { type RuntimeOwnerMutationGate } from "./runtime-owner.js";
 type IndexCodebaseArgs = {
     path: string;
     force?: boolean;

package/dist/core/handlers.js

@@ -2,7 +2,7 @@ import * as fs from "fs";
 import * as path from "path";
 import crypto from "node:crypto";
 import { COLLECTION_LIMIT_MESSAGE, createRuntimeNavigationStore, getSupportedExtensionsForCapability, isLanguageCapabilitySupportedForExtension, isLanguageCapabilitySupportedForFilename, isLanguageCapabilitySupportedForLanguage, } from "@zokizuan/satori-core";
-import { ensureAbsolutePath } from "../utils.js";
+import { absolutePathOrRaw, requireAbsoluteFilesystemPath } from "../utils.js";
 import { DEFAULT_MANAGE_RETRY_AFTER_MS, DEFAULT_WATCH_DEBOUNCE_MS } from "../config.js";
 import { SEARCH_CHANGED_FILES_CACHE_TTL_MS, SEARCH_CHANGED_FIRST_MAX_CHANGED_FILES, SEARCH_MAX_CANDIDATES, SEARCH_MUST_RETRY_ROUNDS, SEARCH_GITIGNORE_FORCE_RELOAD_EVERY_N } from "./search-constants.js";
 import { CallGraphSidecarManager, } from "./call-graph.js";
@@ -29,6 +29,7 @@ import { classifyVectorBackendError, } from "./backend-diagnostics.js";
 import { runSearchExecution, } from "./search-execution.js";
 import { runExactRegistryFastPath } from "./search-exact-fast-path.js";
 import { finalizeSearchResults } from "./search-result-finalization.js";
+import { formatRuntimeOwnerConflictMessage, formatRuntimeOwnerConflictNextStep, } from "./runtime-owner.js";
 const SEARCH_PARTIAL_INDEX_LIMIT_REACHED_WARNING = 'SEARCH_PARTIAL_INDEX:limit_reached';
 const SEARCH_PARTIAL_INDEX_NAVIGATION_UNAVAILABLE_WARNING = 'SEARCH_PARTIAL_INDEX_NAVIGATION_UNAVAILABLE';
 const SEARCH_GROUP_PREVIEW_MAX_CHARS = 800;
@@ -272,6 +273,12 @@ export class ToolHandlers {
             touchWatchedCodebase: this.touchWatchedCodebase.bind(this),
             manageVectorBackendResponse: this.toolResponseBuilders.manageVectorBackendResponse.bind(this.toolResponseBuilders),
             canSyncStaleLocal: this.canSyncStaleLocal.bind(this),
+            getLiveOwnersSummary: async () => {
+                if (!this.runtimeOwnerGate || typeof this.runtimeOwnerGate.getLiveOwnersSummary !== "function") {
+                    return null;
+                }
+                return this.runtimeOwnerGate.getLiveOwnersSummary();
+            },
         };
         this.manageMaintenanceHandlers = new ManageMaintenanceHandlers(manageMaintenanceHandlersHost);
         const getManageIndexingContext = () => this.context;
@@ -617,13 +624,21 @@ export class ToolHandlers {
         return this.buildRuntimeOwnerConflictResponse(action, codebasePath, result);
     }
     buildRuntimeOwnerConflictResponse(action, codebasePath, result) {
+        const conflictingOwners = result.conflictingOwners || [];
         const message = result.message
-            || "Index mutation is blocked because multiple Satori runtimes with different fingerprints/configs are active.";
+            || formatRuntimeOwnerConflictMessage({
+                conflictingOwners,
+            });
         return this.toolResponseBuilders.manageResponse(action, codebasePath, "blocked", message, {
             reason: "runtime_owner_conflict",
             hints: {
-                runtimeOwners: result.conflictingOwners || [],
-                nextStep: "Restart all Satori MCP clients or run the CLI runtime-owner cleanup command, then retry.",
+                runtimeOwners: conflictingOwners,
+                nextStep: formatRuntimeOwnerConflictNextStep(conflictingOwners),
+                nextSteps: [
+                    formatRuntimeOwnerConflictNextStep(conflictingOwners),
+                    "Do not loop create/reindex/sync while runtime_owner_conflict is returned.",
+                    "Search may still work with degraded freshness; mutations stay blocked until a single runtime identity remains.",
+                ],
             }
         });
     }
@@ -1701,7 +1716,7 @@ export class ToolHandlers {
             const vectorBackendDiagnostic = classifyVectorBackendError(error);
             if (vectorBackendDiagnostic) {
                 const payload = this.buildVectorBackendSearchPayload(vectorBackendDiagnostic, {
-                    path: ensureAbsolutePath(input.path),
+                    path: absolutePathOrRaw(input.path),
                     query: input.query,
                     scope: input.scope,
                     groupBy: input.groupBy,
@@ -1721,7 +1736,7 @@ export class ToolHandlers {
             const errorMessage = typeof error === 'string' ? error : (error instanceof Error ? error.message : String(error));
             if (errorMessage === COLLECTION_LIMIT_MESSAGE || errorMessage.includes(COLLECTION_LIMIT_MESSAGE)) {
                 const payload = this.buildInvalidSearchRequestPayload({
-                    path: typeof input.path === 'string' ? ensureAbsolutePath(input.path) : '',
+                    path: typeof input.path === 'string' ? absolutePathOrRaw(input.path) : '',
                     query: typeof input.query === 'string' ? input.query : '',
                     scope: input.scope,
                     groupBy: input.groupBy,
@@ -1746,7 +1761,7 @@ export class ToolHandlers {
                 };
             }
             const payload = this.buildInvalidSearchRequestPayload({
-                path: typeof input.path === 'string' ? ensureAbsolutePath(input.path) : '',
+                path: typeof input.path === 'string' ? absolutePathOrRaw(input.path) : '',
                 query: typeof input.query === 'string' ? input.query : '',
                 scope: input.scope,
                 groupBy: input.groupBy,
@@ -1780,7 +1795,14 @@ export class ToolHandlers {
     async handleReadCode(args) {
         const filePath = typeof args.path === 'string' ? args.path : '';
         try {
-            const absolutePath = ensureAbsolutePath(filePath);
+            const absolutePathResult = requireAbsoluteFilesystemPath(filePath, "path");
+            if (!absolutePathResult.ok) {
+                return {
+                    content: [{ type: "text", text: absolutePathResult.message }],
+                    isError: true
+                };
+            }
+            const absolutePath = absolutePathResult.absolutePath;
             if (!fs.existsSync(absolutePath)) {
                 return {
                     content: [{ type: "text", text: `Error: File '${absolutePath}' not found.` }],

package/dist/core/indexing-recovery.d.ts

@@ -6,7 +6,8 @@ export type InterruptedIndexingRecoveryDecision = {
     stats: {
         indexedFiles: number;
         totalChunks: number;
-        status: 'completed';
+        /** Preserved from marker.indexStatus; legacy markers without the field are completed. */
+        status: 'completed' | 'limit_reached';
     };
     indexFingerprint: IndexFingerprint;
 } | {

package/dist/core/indexing-recovery.js

@@ -1,3 +1,6 @@
+function resolveMarkerIndexStatus(marker) {
+    return marker.indexStatus === 'limit_reached' ? 'limit_reached' : 'completed';
+}
 function fingerprintsMatch(a, b) {
     return a.embeddingProvider === b.embeddingProvider
         && a.embeddingModel === b.embeddingModel
@@ -42,6 +45,7 @@ export function decideInterruptedIndexingRecovery(marker, runtimeFingerprint) {
             message: 'Interrupted indexing detected but completion marker payload is invalid.'
         };
     }
+    const indexStatus = resolveMarkerIndexStatus(marker);
     if (!fingerprintsMatch(marker.fingerprint, runtimeFingerprint)) {
         return {
             action: 'promote_indexed',
@@ -50,7 +54,7 @@ export function decideInterruptedIndexingRecovery(marker, runtimeFingerprint) {
             stats: {
                 indexedFiles: Number(marker.indexedFiles),
                 totalChunks: Number(marker.totalChunks),
-                status: 'completed'
+                status: indexStatus,
             }
         };
     }
@@ -61,7 +65,7 @@ export function decideInterruptedIndexingRecovery(marker, runtimeFingerprint) {
         stats: {
             indexedFiles: Number(marker.indexedFiles),
             totalChunks: Number(marker.totalChunks),
-            status: 'completed'
+            status: indexStatus,
         }
     };
 }

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

@@ -1,11 +1,12 @@
 import { Context } from "@zokizuan/satori-core";
 import type { SnapshotManager } from "./snapshot.js";
 import type { SyncManager } from "./sync.js";
-import { ManageIndexAction } from "./manage-types.js";
+import type { ManageIndexAction } from "./manage-types.js";
 import type { CompletionProofValidationResult } from "./completion-proof.js";
 import { type VectorBackendDiagnostic } from "./backend-diagnostics.js";
 import type { IndexFingerprint } from "../config.js";
 import type { ReindexPreflightResult } from "./working-tree-state.js";
+import type { RuntimeOwnerMutationAction } from "./runtime-owner.js";
 type ToolTextResponse = {
     content: Array<{
         type: "text";
@@ -39,12 +40,12 @@ type ManageIndexingHandlersHost = {
     runtimeFingerprint: IndexFingerprint;
     startBackgroundIndexing?: (codebasePath: string, forceReindex: boolean, writeCollectionName?: string) => Promise<void> | void;
     manageResponse(action: ManageIndexAction | "reindex", path: string, status: string, message: string, options?: Record<string, unknown>): ToolTextResponse;
-    buildRuntimeOwnerConflictResponseIfBlocked(action: ManageIndexAction | "reindex", codebasePath: string): Promise<ToolTextResponse | null>;
+    buildRuntimeOwnerConflictResponseIfBlocked(action: RuntimeOwnerMutationAction, codebasePath: string): Promise<ToolTextResponse | null>;
     recoverStaleIndexingStateIfNeeded(codebasePath: string): Promise<void>;
     getSnapshotIndexingCodebases(): string[];
     getSnapshotCodebaseInfo(codebasePath: string): Record<string, unknown> | undefined;
     getSnapshotIndexedCodebases(): string[];
-    buildManageActionBlockedMessage(codebasePath: string, action: "create" | "reindex" | "repair"): string;
+    buildManageActionBlockedMessage(codebasePath: string, action: Extract<RuntimeOwnerMutationAction, "create" | "reindex" | "repair">): string;
     buildCreateHint(codebasePath: string): Record<string, unknown>;
     buildStatusHint(codebasePath: string): Record<string, unknown>;
     getManageRetryAfterMs(): number;