open-context-engine 0.1.5 → 0.1.6

package/README.md

@@ -37,7 +37,7 @@ Measured with the optional batch rerank API. 40 source-derived tasks, each asked
 
 Requires **macOS, Linux, or Windows**, Node.js 22.14+, Python 3.10+, Git, and configured embedding/reranking services. Go repositories also need Go 1.22+.
 
-Native Windows support is available in version **0.1.3** and later. Run the installation commands in PowerShell. Version **0.1.4** adds automatic worker sharing across MCP sessions to prevent index-lock conflicts. Version **0.1.5** raises the default retrieval output budget to 8,000 tokens; pass `budget: 4000` when a smaller response is sufficient.
+Native Windows support is available in version **0.1.3** and later. Run the installation commands in PowerShell. Version **0.1.4** adds automatic worker sharing across MCP sessions to prevent index-lock conflicts. Version **0.1.5** raises the default retrieval output budget to 8,000 tokens; pass `budget: 4000` when a smaller response is sufficient. Version **0.1.6** reports pending indexing as progress, retries once, and keeps actual indexing failures explicit.
 
 Install from npm, then expand your client's guide. Model settings are shared across clients on the same machine.
 

package/README.zh-CN.md

@@ -37,7 +37,7 @@ OpenContextEngine 是一个**可自行部署、面向 AI 编程助手的代码
 
 需要 **macOS、Linux 或 Windows**、Node.js 22.14+、Python 3.10+、Git，以及已配置好的向量和重排服务。分析 Go 仓库还需要 Go 1.22+。
 
-**0.1.3** 起支持原生 Windows，安装命令可在 PowerShell 中运行。**0.1.4** 起支持多个 MCP 会话自动共享 worker，避免索引锁冲突。**0.1.5** 起默认检索输出预算提高到 8,000 tokens；需要更精简的结果时，可显式传入 `budget: 4000`。
+**0.1.3** 起支持原生 Windows，安装命令可在 PowerShell 中运行。**0.1.4** 起支持多个 MCP 会话自动共享 worker，避免索引锁冲突。**0.1.5** 起默认检索输出预算提高到 8,000 tokens；需要更精简的结果时，可显式传入 `budget: 4000`。 **0.1.6** 起索引更新中会显示进度并自动重试一次，实际索引失败仍明确报错。
 
 通过 npm 安装，展开你所用客户端的教程即可。同一台机器、同一用户下的多个客户端可以共用模型配置。下方链接的详细技术文档目前为英文。
 

package/docs/QUICKSTART.md

@@ -32,7 +32,7 @@ open-context-engine setup --python "C:\Program Files\Python312\python.exe"
 
 Use native absolute project paths such as `C:\Users\you\project` in MCP calls. Generated MCP JSON escapes backslashes automatically.
 
-For internal builds, maintainers can create an archive with `npm pack` and install it with `npm install -g /path/to/open-context-engine-0.1.5.tgz`. See the [release checklist](https://github.com/AnnaSuSu/OpenContextEngine/blob/main/docs/RELEASING.md).
+For internal builds, maintainers can create an archive with `npm pack` and install it with `npm install -g /path/to/open-context-engine-0.1.6.tgz`. See the [release checklist](https://github.com/AnnaSuSu/OpenContextEngine/blob/main/docs/RELEASING.md).
 
 The CLI and package are named `open-context-engine`. The previous `opencontextengine` command remains an alias. Existing configuration and cache directories keep their paths, so saved keys and indexes are reused.
 
@@ -163,7 +163,7 @@ Quote paths that contain spaces. If the generated configuration includes `env` (
 
 - **Command not found:** use the absolute paths above and confirm the Node executable still exists after a Node upgrade.
 - **Tools missing:** check `codex mcp get open-context-engine` for the saved Codex entry, or `/mcp` inside Claude Code for connection status; restart the client after configuration changes.
-- **First search is still indexing:** ask the agent to call `index_status` for the same project. Once it reports ready, retry `search_code`. Large repositories can take longer than a single tool call's timeout. If status reports an error, resolve that error before retrying.
+- **Search reports "Index is updating":** synchronization is still running in the background; the search has not run yet. MCP retries a pending update once, then returns a normal `status: "updating"` response with `retryable: true` if more time is needed. This is not an empty search result. Ask the agent to call `index_status` for the same project and retry `search_code` once ready. Progress shows the current stage and, during embedding, completed/total documents requiring new vectors for this update (cached vectors are excluded). Large repositories can take longer than a single tool call's timeout. If status reports an error, resolve that error before retrying.
 - **Model configuration or authentication errors:** rerun `open-context-engine setup`. `open-context-engine doctor` checks local configuration and dependencies; an actual search checks access to the model APIs. If using SSH forwarding, keep the tunnel running.
 
 Client references: [Codex MCP](https://developers.openai.com/codex/mcp) · [Claude Code MCP](https://code.claude.com/docs/en/mcp).
@@ -172,7 +172,7 @@ Client references: [Codex MCP](https://developers.openai.com/codex/mcp) · [Clau
 
 Saved files are checked every second by default (`OCE_POLL_SECONDS=1`), with a 300 ms debounce (`OCE_DEBOUNCE_SECONDS=0.3`). New files, deletions, renames, and branch changes update the index automatically. Embeddings are reused by model identity and actual input content. Structural analysis conservatively refreshes the affected language group to update references in unchanged files.
 
-Search actively checks source hashes before retrieval and again before returning. It waits up to 30 seconds for synchronization (`freshnessWaitMs`, maximum 120 seconds). Failed updates, timeouts, or edits during retrieval produce explicit errors. Unsaved editor buffers are not indexed.
+Search actively checks source hashes before retrieval and again before returning. Each HTTP search waits up to 30 seconds for synchronization by default (`freshnessWaitMs`, maximum 120 seconds). MCP retries `INDEX_UPDATING` once with an additional wait of `min(freshnessWaitMs, 10000)` milliseconds, giving a default synchronization wait of up to 40 seconds across both attempts; `freshnessWaitMs: 0` disables waiting and retry. HTTP pending responses remain 503 and include `code: "INDEX_UPDATING"`, `retryable: true`, and index progress. MCP presents this specific condition as a normal updating status. Failed updates and edits during retrieval still produce explicit errors. Unsaved editor buffers are not indexed.
 
 Python, JavaScript, TypeScript, and Go files with syntax errors (including unfilled templates) are indexed as plain text with their original paths and line numbers. Healthy files keep their structural analysis; no structural relations are inferred for degraded files. The index remains `ready`, while `index_status` reports `generation.degradedFiles` and `generation.parseDiagnostics` (path, language, error type, line, column, and fallback mode). Search responses include a degraded-file count and MCP displays a short notice. Diagnostics persist across restarts and disappear when the file is repaired or deleted. Model, toolchain, storage, and source-integrity failures still fail explicitly; stale source is never substituted.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-context-engine",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "engines": {
     "node": ">=22.14"
@@ -81,6 +81,6 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "readme": "<div align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/brand/logo-lockup-dark.svg\">\n    <img src=\"assets/brand/logo-lockup.svg\" alt=\"OpenContextEngine\" width=\"660\">\n  </picture>\n  <p><strong>Precise code context for AI coding agents.</strong></p>\n  <p>Find related code across files. Follow its connections. Give your agent the evidence it needs.</p>\n  <p>\n    <a href=\"docs/BENCHMARKS.md#seven-method-comparison\"><img src=\"https://img.shields.io/badge/dev_evidence_coverage-94.79%25-23875b?style=flat-square\" alt=\"Development evidence coverage: 94.79%\"></a>\n    <a href=\"docs/BENCHMARKS.md#seven-method-comparison\"><img src=\"https://img.shields.io/badge/median_retrieval-1.73_s-23875b?style=flat-square\" alt=\"Median retrieval: 1.73 seconds\"></a>\n    <a href=\"docs/BENCHMARKS.md#engineering-validation\"><img src=\"https://img.shields.io/badge/verified_tests-107-23875b?style=flat-square\" alt=\"107 verified tests\"></a>\n    <a href=\"docs/QUICKSTART.md\"><img src=\"https://img.shields.io/badge/MCP-stdio-193c34?style=flat-square\" alt=\"MCP over stdio\"></a>\n  </p>\n  <p><a href=\"#quick-start\">Quick start</a> · <a href=\"docs/BENCHMARKS.md\">Benchmarks</a> · <a href=\"docs/QUICKSTART.md\">MCP setup</a> · <strong>English</strong> | <a href=\"README.zh-CN.md\">简体中文</a></p>\n</div>\n\nOpenContextEngine is a **self-hostable code context engine for AI coding agents**. Connect it to your agent through MCP to help it explore an unfamiliar codebase, locate implementations, and find the related code needed for a fix or feature.\n\nIt indexes your working directory and follows saved changes. Given a natural-language task, it combines semantic and keyword search, code relationships, and reranking to return relevant source snippets with file paths and line numbers, within a fixed context budget.\n\n## Why OpenContextEngine\n\n- **Search beyond exact words.** Describe a behavior; retrieve its implementation and connected code across files.\n- **Understand code structure.** Python, TypeScript, JavaScript, and Go adapters, plus text fallback for other languages, configuration, and scripts.\n- **Stay current as you edit.** Saved changes, file deletions, and branch switches sync automatically. Unchanged embeddings are reused; incomplete updates never replace a complete index.\n- **Work across projects through MCP.** Your agent supplies the project path; indexes start on demand and are reused. `search_code` retrieves evidence; `index_status` reports synchronization.\n\n## Measured results\n\n![Required evidence coverage and observed query time](assets/benchmarks/method-comparison.svg)\n\n**94.79% required evidence coverage · 1.73 s median retrieval · 69/80 queries with complete evidence.** Seven engines, four repositories, the same 4,000-token output budget. OpenContextEngine retained the most required evidence in this internal development evaluation.\n\nMeasured with the optional batch rerank API. 40 source-derived tasks, each asked in Chinese and English. Coverage measures source evidence, not coding-agent success. Timings reflect native retrieval for open tools and SDK client calls for ACE. [Full comparison, configurations, and per-query results →](docs/eval/METHOD_COMPARISON.md)\n\n## Quick start\n\nRequires **macOS, Linux, or Windows**, Node.js 22.14+, Python 3.10+, Git, and configured embedding/reranking services. Go repositories also need Go 1.22+.\n\nNative Windows support is available in version **0.1.3** and later. Run the installation commands in PowerShell. Version **0.1.4** adds automatic worker sharing across MCP sessions to prevent index-lock conflicts. Version **0.1.5** raises the default retrieval output budget to 8,000 tokens; pass `budget: 4000` when a smaller response is sufficient.\n\nInstall from npm, then expand your client's guide. Model settings are shared across clients on the same machine.\n\n<details open>\n<summary><strong>Codex — install, connect, and search</strong></summary>\n\n**1. Install the CLI**\n\nWith Codex CLI already installed, run:\n\n```sh\nnpm install -g open-context-engine\n```\n\n**2. Configure your models**\n\n```sh\nopen-context-engine setup\n```\n\nEnter your embedding and reranking base URLs, API keys, model names, and embedding dimensions. Setup installs isolated Python dependencies and saves your settings. The default reranker uses the ordinary `/rerank` API. [Endpoint examples →](docs/QUICKSTART.md#2-shared-model-configuration)\n\n**3. Add the MCP server**\n\n```sh\ncodex mcp add open-context-engine -- open-context-engine mcp\ncodex mcp get open-context-engine\n```\n\nThe second command checks the saved configuration. These commands assume `open-context-engine` is on the client's `PATH`. For the desktop app or source installations, use the [absolute-path configuration](docs/QUICKSTART.md#client-setup-notes). Restart an already-running Codex client after adding the server.\n\n**4. Search your project**\n\n```sh\ncd /path/to/your-project\ncodex\n```\n\nAsk:\n\n> Use open-context-engine's search_code tool to explain this project's main functionality. Include the entry points and relevant file paths and line numbers.\n\nCodex supplies the project's absolute path as `directory_path`. The first request starts indexing; if it is still building, ask Codex to check `index_status` and retry when ready. Later searches reuse the index, and saved changes update automatically.\n\n</details>\n\n<details>\n<summary><strong>Claude Code — install, connect, and search</strong></summary>\n\n**1. Install the CLI**\n\nWith Claude Code already installed, run:\n\n```sh\nnpm install -g open-context-engine\n```\n\n**2. Configure your models**\n\n```sh\nopen-context-engine setup\n```\n\nEnter your embedding and reranking base URLs, API keys, model names, and embedding dimensions. Setup installs isolated Python dependencies and saves your settings. If you already completed setup for Codex, reuse those settings and skip this step. [Endpoint examples →](docs/QUICKSTART.md#2-shared-model-configuration)\n\n**3. Add the MCP server**\n\n```sh\nclaude mcp add --transport stdio --scope user open-context-engine -- open-context-engine mcp\n```\n\nUser scope makes the server available across your projects. For a shared project configuration, run the command from that project and replace `--scope user` with `--scope project`. These commands assume `open-context-engine` is on the client's `PATH`; see [client setup notes](docs/QUICKSTART.md#client-setup-notes) for absolute paths. Restart an already-running Claude Code session after adding the server.\n\n**4. Search your project**\n\n```sh\ncd /path/to/your-project\nclaude\n```\n\nRun `/mcp` to check the connection, then ask:\n\n> Use open-context-engine's search_code tool to explain this project's main functionality. Include the entry points and relevant file paths and line numbers.\n\nClaude supplies the project's absolute path as `directory_path`. The first request starts indexing; if it is still building, ask Claude to check `index_status` and retry when ready. Later searches reuse the index, and saved changes update automatically.\n\n</details>\n\n<details>\n<summary>Other MCP clients</summary>\n\n[Install and run setup](docs/QUICKSTART.md#1-install), then use the configuration printed by `open-context-engine mcp-config` in your client's supported format. For clients that accept `mcpServers` JSON and can find the installed command on `PATH`:\n\n```json\n{\n  \"mcpServers\": {\n    \"open-context-engine\": {\n      \"command\": \"open-context-engine\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nYour agent supplies the current project's absolute path as `directory_path`. To pin one project, add `\"--root\", \"/absolute/path/to/your-repository\"` to `args`.\n\n</details>\n\n[Model configuration, troubleshooting, and update behavior →](docs/QUICKSTART.md)\n\n## Explore\n\n[Benchmark report](https://github.com/AnnaSuSu/OpenContextEngine/blob/main/docs/BENCHMARKS.md) · [Raw evaluations](https://github.com/AnnaSuSu/OpenContextEngine/tree/main/docs/eval/results) · [Retrieval engine](https://github.com/AnnaSuSu/OpenContextEngine/tree/main/src/retrieval)\n\n## License\n\n[MIT](LICENSE) © 2026 AnnaSuSu.\n\n## Acknowledgments\n\nThanks to the [LINUX DO](https://linux.do/) community.\n",
+  "readme": "<div align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/brand/logo-lockup-dark.svg\">\n    <img src=\"assets/brand/logo-lockup.svg\" alt=\"OpenContextEngine\" width=\"660\">\n  </picture>\n  <p><strong>Precise code context for AI coding agents.</strong></p>\n  <p>Find related code across files. Follow its connections. Give your agent the evidence it needs.</p>\n  <p>\n    <a href=\"docs/BENCHMARKS.md#seven-method-comparison\"><img src=\"https://img.shields.io/badge/dev_evidence_coverage-94.79%25-23875b?style=flat-square\" alt=\"Development evidence coverage: 94.79%\"></a>\n    <a href=\"docs/BENCHMARKS.md#seven-method-comparison\"><img src=\"https://img.shields.io/badge/median_retrieval-1.73_s-23875b?style=flat-square\" alt=\"Median retrieval: 1.73 seconds\"></a>\n    <a href=\"docs/BENCHMARKS.md#engineering-validation\"><img src=\"https://img.shields.io/badge/verified_tests-107-23875b?style=flat-square\" alt=\"107 verified tests\"></a>\n    <a href=\"docs/QUICKSTART.md\"><img src=\"https://img.shields.io/badge/MCP-stdio-193c34?style=flat-square\" alt=\"MCP over stdio\"></a>\n  </p>\n  <p><a href=\"#quick-start\">Quick start</a> · <a href=\"docs/BENCHMARKS.md\">Benchmarks</a> · <a href=\"docs/QUICKSTART.md\">MCP setup</a> · <strong>English</strong> | <a href=\"README.zh-CN.md\">简体中文</a></p>\n</div>\n\nOpenContextEngine is a **self-hostable code context engine for AI coding agents**. Connect it to your agent through MCP to help it explore an unfamiliar codebase, locate implementations, and find the related code needed for a fix or feature.\n\nIt indexes your working directory and follows saved changes. Given a natural-language task, it combines semantic and keyword search, code relationships, and reranking to return relevant source snippets with file paths and line numbers, within a fixed context budget.\n\n## Why OpenContextEngine\n\n- **Search beyond exact words.** Describe a behavior; retrieve its implementation and connected code across files.\n- **Understand code structure.** Python, TypeScript, JavaScript, and Go adapters, plus text fallback for other languages, configuration, and scripts.\n- **Stay current as you edit.** Saved changes, file deletions, and branch switches sync automatically. Unchanged embeddings are reused; incomplete updates never replace a complete index.\n- **Work across projects through MCP.** Your agent supplies the project path; indexes start on demand and are reused. `search_code` retrieves evidence; `index_status` reports synchronization.\n\n## Measured results\n\n![Required evidence coverage and observed query time](assets/benchmarks/method-comparison.svg)\n\n**94.79% required evidence coverage · 1.73 s median retrieval · 69/80 queries with complete evidence.** Seven engines, four repositories, the same 4,000-token output budget. OpenContextEngine retained the most required evidence in this internal development evaluation.\n\nMeasured with the optional batch rerank API. 40 source-derived tasks, each asked in Chinese and English. Coverage measures source evidence, not coding-agent success. Timings reflect native retrieval for open tools and SDK client calls for ACE. [Full comparison, configurations, and per-query results →](docs/eval/METHOD_COMPARISON.md)\n\n## Quick start\n\nRequires **macOS, Linux, or Windows**, Node.js 22.14+, Python 3.10+, Git, and configured embedding/reranking services. Go repositories also need Go 1.22+.\n\nNative Windows support is available in version **0.1.3** and later. Run the installation commands in PowerShell. Version **0.1.4** adds automatic worker sharing across MCP sessions to prevent index-lock conflicts. Version **0.1.5** raises the default retrieval output budget to 8,000 tokens; pass `budget: 4000` when a smaller response is sufficient. Version **0.1.6** reports pending indexing as progress, retries once, and keeps actual indexing failures explicit.\n\nInstall from npm, then expand your client's guide. Model settings are shared across clients on the same machine.\n\n<details open>\n<summary><strong>Codex — install, connect, and search</strong></summary>\n\n**1. Install the CLI**\n\nWith Codex CLI already installed, run:\n\n```sh\nnpm install -g open-context-engine\n```\n\n**2. Configure your models**\n\n```sh\nopen-context-engine setup\n```\n\nEnter your embedding and reranking base URLs, API keys, model names, and embedding dimensions. Setup installs isolated Python dependencies and saves your settings. The default reranker uses the ordinary `/rerank` API. [Endpoint examples →](docs/QUICKSTART.md#2-shared-model-configuration)\n\n**3. Add the MCP server**\n\n```sh\ncodex mcp add open-context-engine -- open-context-engine mcp\ncodex mcp get open-context-engine\n```\n\nThe second command checks the saved configuration. These commands assume `open-context-engine` is on the client's `PATH`. For the desktop app or source installations, use the [absolute-path configuration](docs/QUICKSTART.md#client-setup-notes). Restart an already-running Codex client after adding the server.\n\n**4. Search your project**\n\n```sh\ncd /path/to/your-project\ncodex\n```\n\nAsk:\n\n> Use open-context-engine's search_code tool to explain this project's main functionality. Include the entry points and relevant file paths and line numbers.\n\nCodex supplies the project's absolute path as `directory_path`. The first request starts indexing; if it is still building, ask Codex to check `index_status` and retry when ready. Later searches reuse the index, and saved changes update automatically.\n\n</details>\n\n<details>\n<summary><strong>Claude Code — install, connect, and search</strong></summary>\n\n**1. Install the CLI**\n\nWith Claude Code already installed, run:\n\n```sh\nnpm install -g open-context-engine\n```\n\n**2. Configure your models**\n\n```sh\nopen-context-engine setup\n```\n\nEnter your embedding and reranking base URLs, API keys, model names, and embedding dimensions. Setup installs isolated Python dependencies and saves your settings. If you already completed setup for Codex, reuse those settings and skip this step. [Endpoint examples →](docs/QUICKSTART.md#2-shared-model-configuration)\n\n**3. Add the MCP server**\n\n```sh\nclaude mcp add --transport stdio --scope user open-context-engine -- open-context-engine mcp\n```\n\nUser scope makes the server available across your projects. For a shared project configuration, run the command from that project and replace `--scope user` with `--scope project`. These commands assume `open-context-engine` is on the client's `PATH`; see [client setup notes](docs/QUICKSTART.md#client-setup-notes) for absolute paths. Restart an already-running Claude Code session after adding the server.\n\n**4. Search your project**\n\n```sh\ncd /path/to/your-project\nclaude\n```\n\nRun `/mcp` to check the connection, then ask:\n\n> Use open-context-engine's search_code tool to explain this project's main functionality. Include the entry points and relevant file paths and line numbers.\n\nClaude supplies the project's absolute path as `directory_path`. The first request starts indexing; if it is still building, ask Claude to check `index_status` and retry when ready. Later searches reuse the index, and saved changes update automatically.\n\n</details>\n\n<details>\n<summary>Other MCP clients</summary>\n\n[Install and run setup](docs/QUICKSTART.md#1-install), then use the configuration printed by `open-context-engine mcp-config` in your client's supported format. For clients that accept `mcpServers` JSON and can find the installed command on `PATH`:\n\n```json\n{\n  \"mcpServers\": {\n    \"open-context-engine\": {\n      \"command\": \"open-context-engine\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nYour agent supplies the current project's absolute path as `directory_path`. To pin one project, add `\"--root\", \"/absolute/path/to/your-repository\"` to `args`.\n\n</details>\n\n[Model configuration, troubleshooting, and update behavior →](docs/QUICKSTART.md)\n\n## Explore\n\n[Benchmark report](https://github.com/AnnaSuSu/OpenContextEngine/blob/main/docs/BENCHMARKS.md) · [Raw evaluations](https://github.com/AnnaSuSu/OpenContextEngine/tree/main/docs/eval/results) · [Retrieval engine](https://github.com/AnnaSuSu/OpenContextEngine/tree/main/src/retrieval)\n\n## License\n\n[MIT](LICENSE) © 2026 AnnaSuSu.\n\n## Acknowledgments\n\nThanks to the [LINUX DO](https://linux.do/) community.\n",
   "readmeFilename": "README.md"
 }

package/scripts/retrieval-server.py

@@ -144,7 +144,8 @@ def serve(config):
                     response['diagnostics'] = debug
                 self.reply(200,response)
             except IndexUnavailable as error:
-                self.reply(503,{'error':str(error),'index':live.status()})
+                self.reply(503,{'error':str(error),'code':error.code,
+                               'retryable':error.code == 'INDEX_UPDATING','index':live.status()})
             except Exception as error:
                 print(json.dumps({'event':'search-failed','type':type(error).__name__}),flush=True)
                 self.reply(502,{'error':'Retrieval or model request failed'})

package/src/client.mjs

@@ -18,7 +18,9 @@ export async function search(query,{budget=8000,trace=false,freshnessWaitMs=3000
   if (!response.ok) {
     if (response.status === 503) {
       const body = await response.json();
-      throw new Error(`Index unavailable: ${body.error || 'update pending'}`);
+      throw Object.assign(new Error(`Index unavailable: ${body.error || 'update pending'}`), {
+        code:body.code, index:body.index,
+      });
     }
     if (response.status === 429) {
       const body = await response.json();

package/src/mcp.mjs

@@ -2,6 +2,24 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { search, indexStatus } from './client.mjs';
 
+function updatingResult(error) {
+  const progress = error.index?.progress;
+  let detail = '';
+  if (progress?.stage === 'embedding') {
+    detail = ` Embedding documents: ${progress.completedDocuments}/${progress.totalDocuments} completed for this update.`;
+  } else if (progress?.stage === 'parsing') {
+    detail = ` Parsing ${progress.files} files.`;
+  } else if (progress?.stage === 'finalizing') {
+    detail = ' Finalizing the searchable index.';
+  } else if (progress?.stage === 'source_changed') {
+    detail = ' Saved files changed during indexing; synchronizing the latest version.';
+  }
+  return {isError:false,
+    content:[{type:'text',text:'Index is updating; search has not run yet.' + detail
+      + ' Background synchronization continues. Check index_status for this project and retry search_code once ready.'}],
+    structuredContent:{status:'updating',code:'INDEX_UPDATING',retryable:true,index:error.index}};
+}
+
 export function createMcpServer(config, {resolveConfig, automatic = false} = {}) {
   const workspaceInstructions = automatic
     ? 'Pass directory_path as the absolute directory of the project the user is working on with every tool call. '
@@ -15,9 +33,9 @@ export function createMcpServer(config, {resolveConfig, automatic = false} = {})
   }
   const pathSchema = z.string().min(1).describe('Absolute path to the project directory. Required in automatic workspace mode.');
   const directoryPath = automatic ? pathSchema : pathSchema.optional();
-  const server = new McpServer({name:'open-context-engine',version:'0.1.5'}, {
+  const server = new McpServer({name:'open-context-engine',version:'0.1.6'}, {
     instructions:workspaceInstructions + 'Search for source evidence. Results include source paths and line numbers. '
-      + 'Search waits for saved file changes to be indexed. If an update is pending or fails, inspect index_status and retry after it completes. '
+      + 'Search waits for saved file changes and retries a pending update once. A status of updating means search has not run; inspect index_status and retry once ready. '
       + 'Read target files again before editing, because code may change after a search.',
   });
   const annotations = {readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false};
@@ -27,17 +45,26 @@ export function createMcpServer(config, {resolveConfig, automatic = false} = {})
       + workspaceInstructions
       + 'Uses saved working-tree content, including uncommitted changes; rejects stale results when synchronization fails.',
     inputSchema:{directory_path:directoryPath,query:z.string().trim().min(1).max(8192),budget:z.number().int().min(256).max(8000).default(8000),
-      freshnessWaitMs:z.number().int().min(0).max(120000).default(30000)},
+      freshnessWaitMs:z.number().int().min(0).max(120000).default(30000)
+        .describe('Initial synchronization wait. Pending updates are retried once for up to 10 additional seconds; 0 disables waiting and retry.')},
     annotations,
   }, async ({directory_path,query,budget,freshnessWaitMs}, extra) => {
     try {
       const selected = await selectConfig(directory_path);
-      const result = await search(query,{budget,freshnessWaitMs,config:selected,signal:extra.signal});
+      let result;
+      try {
+        result = await search(query,{budget,freshnessWaitMs,config:selected,signal:extra.signal});
+      } catch (error) {
+        extra.signal.throwIfAborted();
+        if (error.code !== 'INDEX_UPDATING' || freshnessWaitMs === 0) throw error;
+        result = await search(query,{budget,freshnessWaitMs:Math.min(freshnessWaitMs,10000),config:selected,signal:extra.signal});
+      }
       if (result.index?.mode !== 'live') throw new Error('This service uses a frozen index; connect to a service started with --root');
       const warning = result.index.degradedFiles
         ? `Note: ${result.index.degradedFiles} file(s) indexed as plain text after syntax errors; inspect index_status for paths and locations.\n\n` : '';
       return {content:[{type:'text',text:warning + (result.context || 'No matching source context.')}],structuredContent:result};
     } catch (error) {
+      if (error.code === 'INDEX_UPDATING') return updatingResult(error);
       return {isError:true,content:[{type:'text',text:error.message}]};
     }
   });

package/src/retrieval/live.py

@@ -28,6 +28,10 @@ def digest(value):
 class IndexUnavailable(Exception):
     """The requested working tree has no complete, current searchable generation."""
 
+    def __init__(self, message, *, code='INDEX_UNAVAILABLE'):
+        super().__init__(message)
+        self.code = code
+
 
 class SourceChanged(Exception):
     pass
@@ -73,6 +77,7 @@ class LiveIndex:
         self.generation = None
         self.error = None
         self.phase = 'starting'
+        self.progress = None
         self.parse_cache = {}
         self.state.mkdir(parents=True, exist_ok=True, mode=0o700)
         self.lock_file = acquire_writer_lock(self.state/'writer.lock')
@@ -109,7 +114,12 @@ class LiveIndex:
         with self.condition:
             return {'status': self.phase, 'mode': 'live', 'root': str(self.root),
                     'generation': self.generation.info if self.generation else None,
-                    'error': self.error, 'pollSeconds': self.poll}
+                    'error': self.error, 'pollSeconds': self.poll,
+                    'progress': dict(self.progress) if self.progress else None}
+
+    def _progress(self, stage, **counts):
+        with self.condition:
+            self.progress = {'stage': stage, **counts}
 
     def current(self, timeout=30):
         deadline = time.monotonic() + timeout
@@ -125,7 +135,7 @@ class LiveIndex:
                     raise IndexUnavailable('Index update failed: ' + self.error['type'])
                 remaining = deadline - time.monotonic()
                 if remaining <= 0:
-                    raise IndexUnavailable('Index update pending; retry after synchronization')
+                    raise IndexUnavailable('Index is updating; search has not run yet', code='INDEX_UPDATING')
                 self.condition.wait(min(remaining, self.poll))
         raise IndexUnavailable('Index is stopping')
 
@@ -167,6 +177,7 @@ class LiveIndex:
 
     def _build(self, snapshot, identity):
         start = time.monotonic()
+        self._progress('parsing', files=len(snapshot['files']))
         report = {}
         units = source_units(self.root, snapshot['files'], language_options=self.options,
                              cache=self.parse_cache, report=report)
@@ -184,6 +195,7 @@ class LiveIndex:
                         continue
                 missing[key] = text
             entries = list(missing.items())
+            self._progress('embedding', completedDocuments=0, totalDocuments=len(entries))
             for offset in range(0, len(entries), self.batch_size):
                 if self.stop_event.is_set():
                     raise SourceChanged()
@@ -201,6 +213,8 @@ class LiveIndex:
                     vectors[key] = vector
                     db.execute('INSERT OR REPLACE INTO vectors VALUES (?, ?)', (key, vector.tobytes()))
                 db.commit()  # Reuse successful batches even after a concurrent edit.
+                self._progress('embedding', completedDocuments=offset+len(batch), totalDocuments=len(entries))
+        self._progress('finalizing')
         matrix = np.asarray([vectors[key] for key in keys], dtype=np.float32).reshape(len(keys), self.dimensions)
         engine = self._engine(units, matrix)
         if self.stop_event.is_set() or self.scan() != snapshot:
@@ -243,6 +257,7 @@ class LiveIndex:
                     if self.generation and self.generation.identity == identity:
                         with self.condition:
                             self.phase, self.error = 'ready', None
+                            self.progress = None
                         self.stop_event.wait(self.poll)
                         continue
                     if failed_identity == identity and time.monotonic() < retry_at:
@@ -250,6 +265,7 @@ class LiveIndex:
                         continue
                     with self.condition:
                         self.phase, self.error = 'updating', None
+                        self.progress = {'stage': 'checking', 'files': len(snapshot['files'])}
                     if self.stop_event.wait(self.debounce):
                         break
                     if self.scan() != snapshot:
@@ -259,9 +275,11 @@ class LiveIndex:
                         raise SourceChanged()
                     with self.condition:
                         self.generation, self.phase, self.error = generation, 'ready', None
+                        self.progress = None
                         failed_identity = None
                         self.condition.notify_all()
                 except SourceChanged:
+                    self._progress('source_changed')
                     continue
                 except Exception as error:
                     failed_identity, retry_at = identity, time.monotonic() + max(2, self.poll)