@zokizuan/satori-mcp 4.11.2 → 4.11.7

package/README.md

@@ -7,16 +7,45 @@ Read-only MCP server for Satori. It gives coding agents six deterministic tools
 Use the CLI installer for normal setup:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.2 install --client all
-npx -y @zokizuan/satori-cli@0.4.2 doctor
+npx -y @zokizuan/satori-cli@0.4.5 install --client all
+npx -y @zokizuan/satori-cli@0.4.5 doctor
 ```
 
 The CLI installer supports `codex`, `claude`, `opencode`, and `all`. It creates the runtime cache, writes the stable launcher, and writes client config for you. Avoid using `npx` as the resident MCP server command; first-run package resolution can exceed normal MCP startup timeouts.
 
+Use `--profile default|minimal|all-text` to write repo-local `satori.toml` during install:
+
+```bash
+npx -y @zokizuan/satori-cli@0.4.5 install --client all --profile minimal
+```
+
+Profiles control indexing breadth, not search scope. `default` is safe-broad, `minimal` indexes source plus docs/text, and `all-text` indexes additional UTF-8 text files under the size limit. `search_codebase` still defaults to `scope=runtime`.
+
+The repo-local config shape is:
+
+```toml
+[index]
+profile = "minimal"
+```
+
+`satori.toml` is repository index policy, not MCP client config and not provider config. Do not put API keys, model names, Milvus endpoints, or tokens in it. Provider settings belong in the MCP client's runtime environment.
+
+Profile behavior:
+
+- `default`: source, docs/text, config, scripts, infra/query files, and known extensionless files such as `Dockerfile`, `Makefile`, `Justfile`, `Taskfile`, `Procfile`, `Jenkinsfile`, and `.dockerignore`.
+- `minimal`: source plus docs/text only.
+- `all-text`: default plus unknown UTF-8 text files under the size limit. `SATORI_ALL_TEXT_MAX_BYTES` can override the text-file cap.
+
+All profiles still honor `.gitignore`, `.satoriignore`, and the hard denylist for secrets, lockfiles, generated output, dependency folders, binaries, bundles, logs, database dumps, source maps, and snapshots. `satori.toml` is treated as an index-policy control file; search freshness and `manage_index action="sync"` can reconcile ordinary profile/ignore changes, while incompatible fingerprints still return `requires_reindex`.
+
+Codex installs write two companion artifacts by default: the first-party `satori` skill under `~/.codex/skills` and a marked Satori guidance block in `~/.codex/AGENTS.md`. The AGENTS block tells Codex to use Satori for semantic ownership/context discovery first, then use exact navigation and reads for proof.
+
+For Codex, add `--install-guidance-hook` only when you want an installer-managed `SessionStart` reminder in `~/.codex/config.toml`. The hook prints guidance only, suppresses duplicate startup prints for the same working directory, and does not run indexing, search, or provider-backed work.
+
 Advanced direct execution is available through the package bin:
 
 ```bash
-npx -y @zokizuan/satori-mcp@4.11.2 --help
+npx -y @zokizuan/satori-mcp@4.11.7 --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.
@@ -36,9 +65,26 @@ Important defaults:
 
 - `search_codebase` starts with runtime code, grouped by symbol.
 - `search_codebase` runs freshness checks before returning results.
+- 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.
+- 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.
+
+## Navigation Sidecars
+
+Completed full indexes write a derived symbol registry and relationship sidecar. Files remain the source of truth; the registry is the deterministic navigation view for the indexed snapshot.
+
+- 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.
+- `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.
 
 ## Runtime Requirements
 
@@ -85,7 +131,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) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true).
+Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action="status" to observe progress.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
@@ -99,7 +145,7 @@ Manage index lifecycle operations (create/reindex/sync/status/clear) for a codeb
 
 ### `search_codebase`
 
-Unified semantic search with runtime-first defaults (start with scope="runtime"), grouped/raw output modes, and deterministic ranking/freshness behavior. Operators are parsed from a query prefix block: lang:, path:, -path:, must:, exclude: (escape with \\ to keep literals). Use debug:true for explainability payloads, and rely on response hints for remediation (.satoriignore noise handling, navigation fallback, reindex guidance).
+Unified semantic search with runtime-first defaults (start with scope="runtime"), grouped/raw output modes, and deterministic ranking/freshness behavior. Operators are parsed from a query prefix block: lang:, path:, -path:, must:, exclude: (escape with \\ to keep literals). For high-precision queries such as exact identifiers, quoted literal phrases, and strict path filters, search_codebase can use an exact registry fast path or add a bounded tracked-file lexical recovery pass when semantic retrieval under-delivers. Grouped results expose legacy span plus explicit previewSpan/symbolSpan metadata, structured warnings, recommendedNextAction, per-result capabilities/fallbacks, executable nextActions/navigationFallbacks, and remediation hints such as .satoriignore noise handling. Use debug:true for explainability payloads, including debugSummary, exactRegistry, phaseTimingsMs, trackedLexical, and ranking provenance.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
@@ -114,7 +160,7 @@ Unified semantic search with runtime-first defaults (start with scope="runtime")
 
 ### `call_graph`
 
-Traverse the prebuilt call graph sidecar for callers/callees/bidirectional symbol relationships (language support follows the core callGraphQuery capability set; currently TS/JS/Python). When present, testReferences are static call-graph references from test-like files to returned symbols; they are investigation hints and do not prove runtime coverage, assertion coverage, or that a test executed a path.
+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.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
@@ -136,7 +182,7 @@ Return a sidecar-backed symbol outline for one file, including call_graph jump h
 | `end_line` | integer | no |  | Optional end line filter (1-based, inclusive). |
 | `limitSymbols` | integer | no | `500` | Maximum number of returned symbols after line filtering. |
 | `resolveMode` | enum("outline", "exact") | no | `"outline"` | Outline mode returns all symbols (windowed/limited). Exact mode resolves deterministic symbol matches in this file. |
-| `symbolIdExact` | string | no |  | Used with resolveMode="exact": exact symbolId match in the target file. |
+| `symbolIdExact` | string | no |  | Used with resolveMode="exact": exact symbol identifier match in the target file. On symbol-owned flows, pass the symbol's symbolInstanceId. |
 | `symbolLabelExact` | string | no |  | Used with resolveMode="exact": exact symbol label match in the target file. |
 
 ### `read_file`
@@ -149,7 +195,7 @@ Read file content from the local filesystem, with optional 1-based inclusive lin
 | `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. |
-| `open_symbol` | object | no |  | Optional deterministic symbol jump request for this file path. Uses exact symbol resolution within `path` when symbolId/symbolLabel is provided. |
+| `open_symbol` | object | no |  | Optional deterministic symbol jump request for this file path. Uses exact symbol resolution within `path` when symbolId/symbolLabel is provided, and only uses direct span opens when no symbol identity fields are supplied. On symbol-owned flows, symbolId should carry the symbolInstanceId. |
 
 ### `list_codebases`
 
@@ -162,7 +208,7 @@ No parameters.
 
 ## Notes
 
-- `open_symbol` resolves exact symbols inside the same file passed to `read_file.path`.
+- `open_symbol` resolves exact symbols inside the same file passed to `read_file.path`. On symbol-owned flows, `symbolId`/`symbolIdExact` should carry `symbolInstanceId`.
 - `MILVUS_TOKEN` is optional auth; local unauthenticated Milvus only needs `MILVUS_ADDRESS`.
 - MCP startup does not require provider credentials or a live Milvus backend. Provider-backed calls report `MISSING_PROVIDER_CONFIG` when setup is incomplete.
 - `MISSING_PROVIDER_CONFIG` is an active setup failure only when it appears as a tool response `code` or `reason`.

package/dist/cli/args.d.ts

@@ -23,6 +23,8 @@ export type ParsedCommand = {
     kind: "install";
     client: InstallClient;
     dryRun: boolean;
+    installGuidanceHook: boolean;
+    profile?: InstallProfile;
 } | {
     kind: "uninstall";
     client: InstallClient;
@@ -48,6 +50,7 @@ export interface ResolveRawArgsOptions {
     stdinTimeoutMs: number;
 }
 export type InstallClient = "all" | "claude" | "codex" | "opencode";
+export type InstallProfile = "default" | "minimal" | "all-text";
 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

@@ -2,6 +2,9 @@ import fs from "node:fs";
 import { CliError } from "./errors.js";
 const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version", "install", "uninstall"]);
 const PRIMITIVE_TYPES = new Set(["string", "number", "integer", "boolean"]);
+function isWrapperJsonSchema(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function parsePositiveInteger(value, flagName) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -112,6 +115,8 @@ function parseRawArgsMode(args) {
 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") {
@@ -127,9 +132,24 @@ function parseInstallCommand(kind, args) {
             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, client, dryRun };
+    return kind === "install"
+        ? { kind, client, dryRun, installGuidanceHook, profile }
+        : { kind, client, dryRun };
 }
 export function parseCliArgs(argv) {
     const { globals, rest } = parseGlobalOptions(argv);
@@ -282,7 +302,7 @@ function isPrimitiveEnum(enumValues) {
     });
 }
 function unsupportedSchemaReason(schema) {
-    if (!schema || typeof schema !== "object") {
+    if (!isWrapperJsonSchema(schema)) {
         return "schema is not an object";
     }
     if ("oneOf" in schema) {
@@ -305,7 +325,7 @@ function unsupportedSchemaReason(schema) {
     }
     if (schema.type === "array") {
         const itemSchema = schema.items;
-        if (!itemSchema || typeof itemSchema !== "object") {
+        if (!isWrapperJsonSchema(itemSchema)) {
             return "array items schema is missing";
         }
         const itemReason = unsupportedSchemaReason(itemSchema);
@@ -377,7 +397,7 @@ function parsePrimitive(schema, raw) {
     }
 }
 export function parseWrapperArgumentsFromSchema(toolName, inputSchema, wrapperArgs) {
-    if (!inputSchema || typeof inputSchema !== "object") {
+    if (!isWrapperJsonSchema(inputSchema)) {
         throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName} schema is missing or invalid. Use --args-json/--args-file.`, 2);
     }
     const schema = inputSchema;
@@ -395,6 +415,9 @@ export function parseWrapperArgumentsFromSchema(toolName, inputSchema, wrapperAr
     const normalizedToCanonical = new Map();
     const propertySchemas = new Map();
     for (const [propertyName, propertySchema] of Object.entries(properties)) {
+        if (!isWrapperJsonSchema(propertySchema)) {
+            throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName}.${propertyName} uses unsupported schema (schema is not an object). Use --args-json/--args-file.`, 2);
+        }
         const unsupportedReason = unsupportedSchemaReason(propertySchema);
         if (unsupportedReason) {
             throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName}.${propertyName} uses unsupported schema (${unsupportedReason}). Use --args-json/--args-file.`, 2);
@@ -417,6 +440,9 @@ export function parseWrapperArgumentsFromSchema(toolName, inputSchema, wrapperAr
             throw new CliError("E_USAGE", `Unknown flag '${token}' for tool '${toolName}'.`, 2);
         }
         const propertySchema = propertySchemas.get(canonicalName);
+        if (!propertySchema) {
+            throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName}.${canonicalName} schema is missing. Use --args-json/--args-file.`, 2);
+        }
         if (isJsonFlag) {
             const next = wrapperArgs[i + 1];
             if (!next) {
@@ -435,6 +461,9 @@ export function parseWrapperArgumentsFromSchema(toolName, inputSchema, wrapperAr
                 throw new CliError("E_USAGE", `Missing value for ${token}.`, 2);
             }
             const itemSchema = propertySchema.items;
+            if (!isWrapperJsonSchema(itemSchema)) {
+                throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName}.${canonicalName} array items schema is missing. Use --args-json/--args-file.`, 2);
+            }
             const parsedValue = parsePrimitive(itemSchema, next);
             const existing = parsed[canonicalName];
             if (!Array.isArray(existing)) {

package/dist/cli/client.d.ts

@@ -1,5 +1,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+export type ListToolsResult = Awaited<ReturnType<Client["listTools"]>>;
+export type CallToolResult = Awaited<ReturnType<Client["callTool"]>>;
 interface SessionOptions {
     command: string;
     args: string[];
@@ -15,8 +17,8 @@ export declare class CliMcpSession {
     private readonly callTimeoutMs;
     private readonly writeStderr;
     constructor(client: Client, transport: StdioClientTransport, callTimeoutMs: number, writeStderr: (text: string) => void);
-    listTools(): Promise<any>;
-    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    listTools(): Promise<ListToolsResult>;
+    callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
     close(): Promise<void>;
     logProtocolFailure(error: unknown): never;
     wireStderr(): void;

package/dist/cli/index.d.ts

@@ -1,4 +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;
@@ -24,8 +25,8 @@ interface RunCliOptions {
     }) => Promise<CliSession>;
 }
 interface CliSession {
-    listTools(): Promise<any>;
-    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    listTools(): Promise<ListToolsResult>;
+    callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
     close(): Promise<void>;
 }
 export declare function runCli(argv: string[], options?: RunCliOptions): Promise<number>;

package/dist/cli/index.js

@@ -5,18 +5,20 @@ import { fileURLToPath } from "node:url";
 import { parseCliArgs, parseWrapperArgumentsFromSchema, resolveRawArguments } from "./args.js";
 import { connectCliMcpSession } from "./client.js";
 import { asCliError, CliError } from "./errors.js";
-import { emitError, emitJson, inferManageStatusState, parseStructuredEnvelope } from "./format.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";
-const MANAGE_INDEX_MIN_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
 function firstText(result) {
-    const content = result?.content;
+    const content = isRecord(result) ? result.content : undefined;
     if (!Array.isArray(content)) {
         return null;
     }
-    const entry = content.find((item) => item?.type === "text" && typeof item?.text === "string");
-    return entry?.text || null;
+    const entry = content.find((item) => (isRecord(item) && item.type === "text" && typeof item.text === "string"));
+    return entry?.text ?? null;
 }
 function readPackageVersion() {
     try {
@@ -44,7 +46,7 @@ function buildHelpPayload() {
     return {
         usage: "satori-cli <command>",
         commands: [
-            "install [--client all|codex|claude|opencode] [--dry-run]",
+            "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>'",
@@ -60,8 +62,10 @@ function buildHelpPayload() {
     };
 }
 function resolveToolSchema(toolsResult, toolName) {
-    const tools = Array.isArray(toolsResult?.tools) ? toolsResult.tools : [];
-    const tool = tools.find((entry) => entry && entry.name === toolName);
+    const tools = isRecord(toolsResult) && Array.isArray(toolsResult.tools)
+        ? toolsResult.tools
+        : [];
+    const tool = tools.find((entry) => (isRecord(entry) && typeof entry.name === "string" && entry.name === toolName));
     if (!tool) {
         throw new CliError("E_USAGE", `Unknown tool '${toolName}'.`, 2);
     }
@@ -71,39 +75,6 @@ function resolveToolSchema(toolsResult, toolName) {
     }
     return schema;
 }
-function sleep(ms) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, ms);
-        timer.unref();
-    });
-}
-async function pollManageIndexUntilTerminal(pathArg, session, timeoutMs) {
-    const startedAt = Date.now();
-    const pollIntervalMs = 500;
-    while (Date.now() - startedAt < timeoutMs) {
-        await sleep(pollIntervalMs);
-        const statusResult = await session.callTool("manage_index", {
-            action: "status",
-            path: pathArg
-        });
-        const state = inferManageStatusState(statusResult);
-        if (state === "indexing" || state === "unknown") {
-            continue;
-        }
-        return { result: statusResult, state };
-    }
-    throw new CliError("E_CALL_TIMEOUT", `Timed out after ${timeoutMs}ms while waiting for manage_index status.`, 3);
-}
-function shouldWaitManageIndex(toolName, args) {
-    if (toolName !== "manage_index") {
-        return false;
-    }
-    const action = args.action;
-    if (action !== "create" && action !== "reindex") {
-        return false;
-    }
-    return typeof args.path === "string" && args.path.length > 0;
-}
 function summarizeEnvelopeError(writers, envelope) {
     if (!envelope) {
         return;
@@ -120,7 +91,7 @@ function maybeEmitTextSummary(writers, result) {
     }
 }
 function evaluateToolResultForError(result, writers) {
-    if (result?.isError === true) {
+    if (isRecord(result) && result.isError === true) {
         const message = firstText(result) || "tool call failed";
         writers.writeStderr(`E_TOOL_ERROR ${message}\n`);
         return 1;
@@ -132,9 +103,8 @@ function evaluateToolResultForError(result, writers) {
     }
     return null;
 }
-async function invokeTool(toolName, args, session, callTimeoutMs, writers, format) {
+async function invokeTool(toolName, args, session, _callTimeoutMs, writers, format) {
     let result = await session.callTool(toolName, args);
-    let manageWaitState = null;
     const initialErrorExit = evaluateToolResultForError(result, writers);
     if (initialErrorExit !== null) {
         emitJson(writers, result);
@@ -143,12 +113,6 @@ async function invokeTool(toolName, args, session, callTimeoutMs, writers, forma
         }
         return initialErrorExit;
     }
-    if (shouldWaitManageIndex(toolName, args)) {
-        const effectiveManagePollTimeoutMs = Math.max(callTimeoutMs, MANAGE_INDEX_MIN_POLL_TIMEOUT_MS);
-        const polled = await pollManageIndexUntilTerminal(args.path, session, effectiveManagePollTimeoutMs);
-        result = polled.result;
-        manageWaitState = polled.state;
-    }
     emitJson(writers, result);
     if (format === "text") {
         maybeEmitTextSummary(writers, result);
@@ -157,10 +121,6 @@ async function invokeTool(toolName, args, session, callTimeoutMs, writers, forma
     if (finalErrorExit !== null) {
         return finalErrorExit;
     }
-    if (manageWaitState === "indexfailed" || manageWaitState === "requires_reindex" || manageWaitState === "not_indexed") {
-        emitError(writers, "E_TOOL_ERROR", `manage_index terminal state=${manageWaitState}`);
-        return 1;
-    }
     return 0;
 }
 export async function runCli(argv, options = {}) {

package/dist/cli/install.d.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import type { InstallClient } from "./args.js";
+import type { InstallClient, InstallProfile } from "./args.js";
 type ExecFileSyncLike = typeof execFileSync;
 type ClientName = Exclude<InstallClient, "all">;
 export interface ManagedRuntimeCommand {
@@ -10,9 +10,12 @@ export interface InstallCommandInput {
     kind: "install" | "uninstall";
     client: InstallClient;
     dryRun: boolean;
+    installGuidanceHook?: boolean;
+    profile?: InstallProfile;
 }
 export interface InstallCommandOptions {
     homeDir?: string;
+    repoDir?: string;
     packageSpecifier?: string;
     skillAssetRoot?: string;
     runtimeCommand?: ManagedRuntimeCommand;
@@ -33,6 +36,9 @@ export interface InstallCommandResult {
     action: "install" | "uninstall";
     client: InstallClient;
     dryRun: boolean;
+    profile?: InstallProfile;
+    profileConfigPath?: string;
+    profileConfigChanged?: boolean;
     results: ClientInstallResult[];
 }
 export declare function executeInstallCommand(command: InstallCommandInput, options?: InstallCommandOptions): InstallCommandResult;