opencode-codebase-index 0.23.0 → 0.25.0

package/dist/cli.cjs

@@ -730,6 +730,17 @@ var EMBEDDING_MODELS = {
       maxTokens: 2048,
       costPer1MTokens: 0.15,
       taskAble: true
+    },
+    "gemini-embedding-2": {
+      provider: "google",
+      model: "gemini-embedding-2",
+      // Keep a conservative, testable default embedding dimension. Gemini Embedding 2 supports
+      // flexible dimensions via outputDimensionality.
+      dimensions: 1536,
+      maxTokens: 8192,
+      costPer1MTokens: 0.15,
+      taskAble: false,
+      promptStyle: "embedding-2"
     }
   },
   "openai": {
@@ -763,26 +774,15 @@ var EMBEDDING_MODELS = {
       maxTokens: 512,
       costPer1MTokens: 0
     }
-  },
-  "github-copilot": {
-    "text-embedding-3-small": {
-      provider: "github-copilot",
-      model: "text-embedding-3-small",
-      dimensions: 1536,
-      maxTokens: 8191,
-      costPer1MTokens: 0
-    }
   }
 };
 var DEFAULT_PROVIDER_MODELS = {
-  "github-copilot": "text-embedding-3-small",
   "openai": "text-embedding-3-small",
   "google": "gemini-embedding-001",
   "ollama": "nomic-embed-text"
 };
 var AUTO_DETECT_PROVIDER_ORDER = [
   "ollama",
-  "github-copilot",
   "openai",
   "google"
 ];
@@ -808,6 +808,9 @@ function getDefaultIndexingConfig() {
     maxDepth: 5,
     maxFilesPerDirectory: 100,
     fallbackToTextOnMaxChunks: true,
+    // Must stay in sync with DEFAULT_LINES_PER_CHUNK in native/src/lib.rs (the napi
+    // fallback used when a native caller omits the argument).
+    linesPerChunk: 30,
     gitBlame: { enabled: false }
   };
 }
@@ -941,6 +944,7 @@ function parseConfig(raw) {
     maxDepth: typeof rawIndexing.maxDepth === "number" ? rawIndexing.maxDepth < -1 ? -1 : rawIndexing.maxDepth : defaultIndexing.maxDepth,
     maxFilesPerDirectory: typeof rawIndexing.maxFilesPerDirectory === "number" ? Math.max(1, rawIndexing.maxFilesPerDirectory) : defaultIndexing.maxFilesPerDirectory,
     fallbackToTextOnMaxChunks: typeof rawIndexing.fallbackToTextOnMaxChunks === "boolean" ? rawIndexing.fallbackToTextOnMaxChunks : defaultIndexing.fallbackToTextOnMaxChunks,
+    linesPerChunk: typeof rawIndexing.linesPerChunk === "number" && Number.isFinite(rawIndexing.linesPerChunk) ? Math.min(Math.max(1, Math.floor(rawIndexing.linesPerChunk)), 4294967295) : defaultIndexing.linesPerChunk,
     gitBlame: {
       enabled: rawIndexing.gitBlame && typeof rawIndexing.gitBlame === "object" && typeof rawIndexing.gitBlame.enabled === "boolean" ? rawIndexing.gitBlame.enabled : defaultIndexing.gitBlame.enabled
     }
@@ -983,6 +987,7 @@ function parseConfig(raw) {
   let embeddingModel;
   let customProvider;
   let reranker;
+  const githubCopilotDeprecationMessage = '`embeddingProvider: "github-copilot"` is deprecated and no longer available. Migrate existing configs to `embeddingProvider: "google"` and select an explicit Google model. For existing indexes, run `index_codebase` with `force: true` after changing to `gemini-embedding-001` or `gemini-embedding-2` to rebuild embeddings. See docs/configuration.md for details.';
   if (embeddingProviderValue === "custom") {
     embeddingProvider = "custom";
     const rawCustom = input.customProvider && typeof input.customProvider === "object" ? input.customProvider : null;
@@ -1022,6 +1027,8 @@ function parseConfig(raw) {
     } else if (rawEmbeddingModel) {
       embeddingModel = DEFAULT_PROVIDER_MODELS[embeddingProvider];
     }
+  } else if (embeddingProviderValue === "github-copilot") {
+    throw new Error(githubCopilotDeprecationMessage);
   } else {
     embeddingProvider = "auto";
   }
@@ -1052,10 +1059,21 @@ function parseConfig(raw) {
       timeoutMs: typeof rawReranker.timeoutMs === "number" ? Math.max(1e3, Math.floor(rawReranker.timeoutMs)) : 1e4
     };
   }
+  const rawEmbedding = input.embedding && typeof input.embedding === "object" ? input.embedding : {};
+  const rawEmbeddingBatch = rawEmbedding.batch && typeof rawEmbedding.batch === "object" ? rawEmbedding.batch : null;
+  const embeddingMaxBatchItems = typeof rawEmbeddingBatch?.maxBatchItems === "number" && Number.isFinite(rawEmbeddingBatch.maxBatchItems) ? Math.max(1, Math.floor(rawEmbeddingBatch.maxBatchItems)) : void 0;
+  const embeddingMaxBatchTokens = typeof rawEmbeddingBatch?.maxBatchTokens === "number" && Number.isFinite(rawEmbeddingBatch.maxBatchTokens) ? Math.max(1, Math.floor(rawEmbeddingBatch.maxBatchTokens)) : void 0;
+  const embedding = embeddingMaxBatchItems !== void 0 || embeddingMaxBatchTokens !== void 0 ? {
+    batch: {
+      ...embeddingMaxBatchItems !== void 0 ? { maxBatchItems: embeddingMaxBatchItems } : {},
+      ...embeddingMaxBatchTokens !== void 0 ? { maxBatchTokens: embeddingMaxBatchTokens } : {}
+    }
+  } : {};
   return {
     embeddingProvider,
     embeddingModel,
     customProvider,
+    embedding,
     scope: isValidScope(scopeValue) ? scopeValue : "project",
     include: includeValue ?? DEFAULT_INCLUDE,
     exclude: excludeValue ?? DEFAULT_EXCLUDE,
@@ -2551,8 +2569,6 @@ async function tryDetectProvider() {
 }
 async function getProviderCredentials(provider) {
   switch (provider) {
-    case "github-copilot":
-      return getGitHubCopilotCredentials();
     case "openai":
       return getOpenAICredentials();
     case "google":
@@ -2563,22 +2579,6 @@ async function getProviderCredentials(provider) {
       return null;
   }
 }
-function getGitHubCopilotCredentials() {
-  const authData = loadOpenCodeAuth();
-  const copilotAuth = authData["github-copilot"] || authData["github-copilot-enterprise"];
-  if (!copilotAuth || copilotAuth.type !== "oauth") {
-    return null;
-  }
-  const auth = copilotAuth;
-  const baseUrl = auth.enterpriseUrl ? `https://copilot-api.${auth.enterpriseUrl.replace(/^https?:\/\//, "").replace(/\/$/, "")}` : "https://models.github.ai";
-  return {
-    provider: "github-copilot",
-    baseUrl,
-    refreshToken: copilotAuth.refresh,
-    accessToken: copilotAuth.access,
-    tokenExpires: copilotAuth.expires
-  };
-}
 function getOpenAICredentials() {
   const authData = loadOpenCodeAuth();
   const openaiAuth = authData["openai"];
@@ -2704,8 +2704,6 @@ async function tryDetectOllamaProvider() {
 }
 function getProviderDisplayName(provider) {
   switch (provider) {
-    case "github-copilot":
-      return "GitHub Copilot";
     case "openai":
       return "OpenAI";
     case "google":
@@ -2930,44 +2928,6 @@ var CustomEmbeddingProvider = class extends BaseEmbeddingProvider {
   }
 };
 
-// src/embeddings/providers/github-copilot.ts
-var GitHubCopilotEmbeddingProvider = class extends BaseEmbeddingProvider {
-  constructor(credentials, modelInfo) {
-    super(credentials, modelInfo);
-  }
-  getToken() {
-    if (!this.credentials.refreshToken) {
-      throw new Error("No OAuth token available for GitHub");
-    }
-    return this.credentials.refreshToken;
-  }
-  async embedBatch(texts) {
-    const token = this.getToken();
-    const response = await fetch(`${this.credentials.baseUrl}/inference/embeddings`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-        Accept: "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2022-11-28"
-      },
-      body: JSON.stringify({
-        model: `openai/${this.modelInfo.model}`,
-        input: texts
-      })
-    });
-    if (!response.ok) {
-      const error = (await response.text()).slice(0, 500);
-      throw new Error(`GitHub Copilot embedding API error: ${response.status} - ${error}`);
-    }
-    const data = await response.json();
-    return {
-      embeddings: data.data.map((d) => d.embedding),
-      totalTokensUsed: data.usage.total_tokens
-    };
-  }
-};
-
 // src/embeddings/providers/google.ts
 var GoogleEmbeddingProvider = class _GoogleEmbeddingProvider extends BaseEmbeddingProvider {
   static BATCH_SIZE = 20;
@@ -2975,24 +2935,30 @@ var GoogleEmbeddingProvider = class _GoogleEmbeddingProvider extends BaseEmbeddi
     super(credentials, modelInfo);
   }
   async embedQuery(query) {
-    const taskType = this.modelInfo.taskAble ? "CODE_RETRIEVAL_QUERY" : void 0;
-    const result = await this.embedWithTaskType([query], taskType);
+    const taskType = this.modelInfo.model === "gemini-embedding-001" && this.modelInfo.taskAble ? "CODE_RETRIEVAL_QUERY" : void 0;
+    const texts = [
+      this.modelInfo.model === "gemini-embedding-2" ? `task: code retrieval | query: ${query}` : query
+    ];
+    const result = await this.embedWithTaskType(texts, taskType);
     return {
       embedding: result.embeddings[0],
       tokensUsed: result.totalTokensUsed
     };
   }
   async embedDocument(document) {
-    const taskType = this.modelInfo.taskAble ? "RETRIEVAL_DOCUMENT" : void 0;
-    const result = await this.embedWithTaskType([document], taskType);
+    const taskType = this.modelInfo.model === "gemini-embedding-001" && this.modelInfo.taskAble ? "RETRIEVAL_DOCUMENT" : void 0;
+    const result = await this.embedWithTaskType([
+      this.modelInfo.model === "gemini-embedding-2" ? `title: none | text: ${document}` : document
+    ], taskType);
     return {
       embedding: result.embeddings[0],
       tokensUsed: result.totalTokensUsed
     };
   }
   async embedBatch(texts) {
-    const taskType = this.modelInfo.taskAble ? "RETRIEVAL_DOCUMENT" : void 0;
-    return this.embedWithTaskType(texts, taskType);
+    const taskType = this.modelInfo.model === "gemini-embedding-001" && this.modelInfo.taskAble ? "RETRIEVAL_DOCUMENT" : void 0;
+    const formattedTexts = this.modelInfo.model === "gemini-embedding-2" ? texts.map((text) => `title: none | text: ${text}`) : texts;
+    return this.embedWithTaskType(formattedTexts, taskType);
   }
   async embedWithTaskType(texts, taskType) {
     const batches = [];
@@ -3042,6 +3008,10 @@ var GoogleEmbeddingProvider = class _GoogleEmbeddingProvider extends BaseEmbeddi
 var OllamaEmbeddingProvider = class _OllamaEmbeddingProvider extends BaseEmbeddingProvider {
   static MIN_TRUNCATION_CHARS = 512;
   static REQUEST_TIMEOUT_MS = 12e4;
+  // Set when /api/embed returns 404 so subsequent multi-text batches skip the
+  // batched endpoint and go straight to the legacy per-text path (one probe per
+  // old ollama install, not one probe per batch).
+  batchEndpointUnavailable = false;
   constructor(credentials, modelInfo) {
     super(credentials, modelInfo);
   }
@@ -3059,6 +3029,21 @@ var OllamaEmbeddingProvider = class _OllamaEmbeddingProvider extends BaseEmbeddi
     const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
     return message.includes("context length") && (message.includes("exceed") || message.includes("exceeded") || message.includes("too long")) || message.includes("input length exceeds the context length") || message.includes("context length exceeded");
   }
+  // True for a 404 from the newer /api/embed endpoint, i.e. an ollama version that
+  // does not provide it. embedBatch uses this to fall back to the legacy per-text
+  // /api/embeddings path so old ollama installs do not regress.
+  isBatchEndpointUnavailableError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("Ollama /api/embed not available");
+  }
+  // True for a malformed /api/embed response (wrong vector count or a bad vector).
+  // embedBatch falls back to the per-text path on this so a bad batch response
+  // re-embeds each text cleanly. A text that then fails per-text is not isolated
+  // here; it is isolated on the recovery run, which re-embeds one text per request.
+  isBatchValidationError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("invalid embedding batch");
+  }
   buildTruncationCandidates(text) {
     const baseMaxChars = Math.max(1, this.modelInfo.maxTokens * 4);
     const candidateLimits = /* @__PURE__ */ new Set();
@@ -3160,7 +3145,74 @@ var OllamaEmbeddingProvider = class _OllamaEmbeddingProvider extends BaseEmbeddi
       tokensUsed: this.estimateTokens(text)
     };
   }
-  async embedBatch(texts) {
+  // Embeds many texts in one POST /api/embed request (input: string[]). Ollama
+  // encodes each input independently, so the model context length applies per input
+  // (the upstream splitter already bounds each input), not over the batch. This
+  // amortizes N HTTP round-trips into one.
+  async embedMany(texts) {
+    const controller = new AbortController();
+    const timeout = setTimeout(
+      () => controller.abort(),
+      _OllamaEmbeddingProvider.REQUEST_TIMEOUT_MS
+    );
+    let response;
+    try {
+      response = await fetch(`${this.credentials.baseUrl}/api/embed`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          model: this.modelInfo.model,
+          input: texts,
+          truncate: false
+        }),
+        signal: controller.signal
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error(
+          `Ollama embedding request timed out after ${_OllamaEmbeddingProvider.REQUEST_TIMEOUT_MS}ms`
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (!response.ok) {
+      const error = (await response.text()).slice(0, 500);
+      if (response.status === 404) {
+        throw new Error(`Ollama /api/embed not available: ${response.status} - ${error}`);
+      }
+      throw new Error(`Ollama embedding API error: ${response.status} - ${error}`);
+    }
+    let parsed;
+    try {
+      parsed = await response.json();
+    } catch {
+      throw new Error(
+        `Ollama returned an invalid embedding batch; expected ${texts.length} vectors of ${this.modelInfo.dimensions} finite dimensions`
+      );
+    }
+    const data = parsed && typeof parsed === "object" ? parsed : {};
+    if (!Array.isArray(data.embeddings) || data.embeddings.length !== texts.length || data.embeddings.some(
+      (value) => !Array.isArray(value) || value.length !== this.modelInfo.dimensions || value.some((v) => typeof v !== "number" || !Number.isFinite(v))
+    )) {
+      throw new Error(
+        `Ollama returned an invalid embedding batch; expected ${texts.length} vectors of ${this.modelInfo.dimensions} finite dimensions`
+      );
+    }
+    return {
+      embeddings: data.embeddings,
+      totalTokensUsed: texts.reduce((sum, text) => sum + this.estimateTokens(text), 0)
+    };
+  }
+  // Per-text /api/embeddings path shared by the single-text fast path and the
+  // batch fallback. Uses the legacy endpoint one text at a time, so each text gets
+  // its own truncation safety net and a vector validated on its own. A text that
+  // hard-fails per-text throws here and fails the whole request batch; the recovery
+  // run re-embeds one text per request to isolate it.
+  async embedOneByOne(texts) {
     const results = [];
     for (const text of texts) {
       results.push(await this.embedSingleWithFallback(text));
@@ -3170,6 +3222,26 @@ var OllamaEmbeddingProvider = class _OllamaEmbeddingProvider extends BaseEmbeddi
       totalTokensUsed: results.reduce((sum, r) => sum + r.tokensUsed, 0)
     };
   }
+  async embedBatch(texts) {
+    if (texts.length === 0) {
+      return { embeddings: [], totalTokensUsed: 0 };
+    }
+    if (texts.length === 1 || this.batchEndpointUnavailable) {
+      return this.embedOneByOne(texts);
+    }
+    try {
+      return await this.embedMany(texts);
+    } catch (error) {
+      if (this.isBatchEndpointUnavailableError(error)) {
+        this.batchEndpointUnavailable = true;
+        return this.embedOneByOne(texts);
+      }
+      if (!this.isContextLengthError(error) && !this.isBatchValidationError(error)) {
+        throw error;
+      }
+      return this.embedOneByOne(texts);
+    }
+  }
 };
 
 // src/embeddings/providers/openai.ts
@@ -3204,8 +3276,6 @@ var OpenAIEmbeddingProvider = class extends BaseEmbeddingProvider {
 // src/embeddings/provider.ts
 function createEmbeddingProvider(configuredProviderInfo) {
   switch (configuredProviderInfo.provider) {
-    case "github-copilot":
-      return new GitHubCopilotEmbeddingProvider(configuredProviderInfo.credentials, configuredProviderInfo.modelInfo);
     case "openai":
       return new OpenAIEmbeddingProvider(configuredProviderInfo.credentials, configuredProviderInfo.modelInfo);
     case "google":
@@ -3540,6 +3610,26 @@ function formatCostEstimate(estimate) {
 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
 `;
 }
+function formatDryRunEstimate(estimate) {
+  return `Dry run: parsed the file set to measure the embedding workload. No embedding requests were made and the index was not changed.
+
+  Files to embed:   ${estimate.filesCount.toLocaleString()}
+  Chunks to embed:  ${estimate.chunksCount.toLocaleString()}
+  Tokens to embed:  ${estimate.tokensToEmbed.toLocaleString()}
+
+The "Tokens to embed" value uses the local estimateTokens(text) = ceil(len/4). It
+matches the live "Tokens used" counter only for providers that report usage on the
+same basis (ollama); for providers that report a server tokenizer count (OpenAI,
+Gemini, custom) it is only an estimate.
+
+For a matching provider and a project-scoped force index, the force pass clears its
+own cached embeddings, so the live counter climbs to this number. A force index on a
+shared global index can reuse cached embeddings from other projects, and an
+incremental index counts cached chunks that are not re-embedded; in both cases this
+number is an upper bound on the live counter, so a progress percent against this
+total tops out below 100%.
+`;
+}
 function formatBytes(bytes) {
   if (bytes === 0) return "0 B";
   const k = 1024;
@@ -4224,12 +4314,12 @@ try {
 }
 
 // src/native/parsing.ts
-function parseFileAsText(filePath, content) {
-  const result = native.parseFileAsText(filePath, content);
+function parseFileAsText(filePath, content, linesPerChunk) {
+  const result = native.parseFileAsText(filePath, content, linesPerChunk);
   return result.map(mapChunk);
 }
-function parseFiles(files) {
-  const result = native.parseFiles(files);
+function parseFiles(files, linesPerChunk) {
+  const result = native.parseFiles(files, linesPerChunk);
   return result.map((f) => ({
     path: f.path,
     chunks: f.chunks.map(mapChunk),
@@ -4306,13 +4396,13 @@ var VectorStore = class {
     const metadata = items.map((i) => JSON.stringify(i.metadata));
     this.inner.addBatch(ids, vectors, metadata);
   }
-  search(queryVector, limit = 10) {
+  search(queryVector, limit = 10, allowedIds) {
     if (queryVector.length !== this.dimensions) {
       throw new Error(
         `Query vector dimension mismatch: expected ${this.dimensions}, got ${queryVector.length}`
       );
     }
-    const results = this.inner.search(queryVector, limit);
+    const results = allowedIds === void 0 ? this.inner.search(queryVector, limit) : this.inner.searchFiltered(queryVector, limit, allowedIds);
     return results.map((r) => ({
       id: r.id,
       score: r.score,
@@ -4540,6 +4630,10 @@ var Database = class _Database {
     this.throwIfClosed();
     return this.inner.getBranchChunkIds(branch);
   }
+  getChunkIdsByBlameDate(since, until) {
+    this.throwIfClosed();
+    return this.inner.getChunkIdsByBlameDate(since, until);
+  }
   getBranchDelta(branch, baseBranch) {
     this.throwIfClosed();
     return this.inner.getBranchDelta(branch, baseBranch);
@@ -5501,6 +5595,9 @@ function resolveWorktreeFallbackPath(projectRoot, relativePath) {
   const fallbackPath = path10.join(mainRepoRoot, relativePath);
   return (0, import_fs7.existsSync)(fallbackPath) ? fallbackPath : null;
 }
+function getHostProjectConfigRelativePath(host) {
+  return getProjectConfigRelativePath(host);
+}
 function getProjectConfigCandidatePaths(projectRoot, host) {
   const candidates = [path10.join(projectRoot, getProjectConfigRelativePath(host))];
   if (host !== "opencode") {
@@ -5592,6 +5689,9 @@ function resolveProjectConfigPath(projectRoot, host) {
   const candidates = getProjectConfigCandidatePaths(projectRoot, host);
   return candidates.find((candidate) => (0, import_fs7.existsSync)(candidate)) ?? path10.join(projectRoot, getProjectConfigRelativePath(host));
 }
+function resolveWritableProjectConfigPath(projectRoot, host) {
+  return path10.join(projectRoot, getProjectConfigRelativePath(host));
+}
 function resolveProjectIndexPath(projectRoot, scope, host) {
   if (scope === "global") {
     return resolveGlobalIndexPath(host);
@@ -6297,6 +6397,10 @@ function scoreCandidate(query, intent, candidate, originalIndex) {
   let boost = 0;
   if (intent.primary === "conceptual") {
     boost += Math.min(0.14, overlap * 0.14);
+    if (intent.preferSourcePaths) {
+      boost += implementationPath ? 0.32 : 0;
+      if (testPath || fixturePath || docsPath) boost -= 0.35;
+    }
     if (generatedOrVendor) boost -= 0.18;
     if (importChunk || weakContainer) boost -= 0.04;
   } else if (intent.primary === "test") {
@@ -6751,6 +6855,9 @@ var CALL_GRAPH_SYMBOL_CHUNK_TYPES = /* @__PURE__ */ new Set([
   "enum_declaration",
   "function_definition",
   "class_definition",
+  // Ruby module/class symbols that are declaration-bearing and navigable.
+  "class",
+  "module",
   "class_specifier",
   "struct_specifier",
   "namespace_definition",
@@ -7211,6 +7318,19 @@ function parseOwner(value) {
   if (typeof candidate.startedAt !== "string" || Number.isNaN(Date.parse(candidate.startedAt))) return null;
   if (typeof candidate.operation !== "string" || !VALID_OPERATIONS.has(candidate.operation)) return null;
   if (typeof candidate.token !== "string" || !UUID_PATTERN.test(candidate.token)) return null;
+  if (candidate.recoveryProtocolVersion !== void 0 && candidate.recoveryProtocolVersion !== 1) return null;
+  if (candidate.projectRoot !== void 0 && typeof candidate.projectRoot !== "string") return null;
+  if (candidate.scopedRoots !== void 0) {
+    if (!Array.isArray(candidate.scopedRoots) || candidate.scopedRoots.some((root) => typeof root !== "string")) {
+      return null;
+    }
+  }
+  if (candidate.clearRecovery !== void 0) {
+    const recovery = candidate.clearRecovery;
+    if (typeof recovery !== "object" || recovery === null || recovery.phase !== "clearing" || typeof recovery.embeddingProvider !== "string" || recovery.embeddingProvider.length === 0 || typeof recovery.embeddingModel !== "string" || recovery.embeddingModel.length === 0 || !Number.isInteger(recovery.embeddingDimensions) || (recovery.embeddingDimensions ?? 0) <= 0 || typeof recovery.embeddingStrategyVersion !== "string" || recovery.embeddingStrategyVersion.length === 0 || recovery.compatibilityDecision !== "compatible" && recovery.compatibilityDecision !== "embedding-strategy-mismatch" && recovery.compatibilityDecision !== "incompatible" || candidate.operation !== "clear" && candidate.operation !== "force-index") {
+      return null;
+    }
+  }
   return candidate;
 }
 function parseReclaimOwner(value) {
@@ -7451,13 +7571,18 @@ function isTransientIndexLockContention(error) {
   if (!isIndexLockContentionError(error) || !("reason" in error)) return false;
   return error.reason === "active" || error.reason === "reclaiming";
 }
-function acquireIndexLock(indexPath, operation) {
+function acquireIndexLock(indexPath, operation, recoveryScope) {
   (0, import_fs9.mkdirSync)(indexPath, { recursive: true });
   const canonicalIndexPath = import_fs9.realpathSync.native(indexPath);
   const lockPath = path13.join(canonicalIndexPath, "indexing.lock");
   cleanupDeadPublicationCandidates(canonicalIndexPath);
   for (let attempt = 0; attempt < 6; attempt += 1) {
-    const owner = createOwner(operation);
+    const owner = recoveryScope === void 0 ? createOwner(operation) : {
+      ...createOwner(operation),
+      recoveryProtocolVersion: 1,
+      projectRoot: recoveryScope.projectRoot,
+      scopedRoots: recoveryScope.scopedRoots
+    };
     if (publishJsonDirectory(lockPath, owner)) {
       const lease = {
         canonicalIndexPath,
@@ -7522,6 +7647,33 @@ function releaseIndexLock(lease) {
   }
   return true;
 }
+function setIndexLockClearRecoveryState(lease, clearRecovery) {
+  const currentOwner = readDirectoryOwner(lease.lockPath);
+  if (!currentOwner || !sameOwner(currentOwner, lease.owner)) {
+    throw new Error(`Lost ownership of index mutation lease ${lease.owner.token}`);
+  }
+  const nextOwner = { ...currentOwner };
+  if (clearRecovery === null) {
+    delete nextOwner.clearRecovery;
+  } else {
+    nextOwner.clearRecovery = clearRecovery;
+  }
+  const ownerPath = path13.join(lease.lockPath, OWNER_FILE_NAME);
+  const temporaryPath = path13.join(
+    lease.lockPath,
+    `${OWNER_FILE_NAME}.tmp.${lease.owner.pid}.${lease.owner.token}.${(0, import_crypto2.randomUUID)()}`
+  );
+  try {
+    (0, import_fs9.writeFileSync)(temporaryPath, JSON.stringify(nextOwner), {
+      encoding: "utf-8",
+      flag: "wx",
+      mode: 384
+    });
+    retryTransientFilesystemOperation(() => (0, import_fs9.renameSync)(temporaryPath, ownerPath));
+  } finally {
+    if ((0, import_fs9.existsSync)(temporaryPath)) (0, import_fs9.rmSync)(temporaryPath, { force: true });
+  }
+}
 function createLeaseTemporaryPath(targetPath, owner, kind = "tmp") {
   if (kind === "bak") return `${targetPath}.bak.${owner.pid}.${owner.token}`;
   temporaryCounter += 1;
@@ -7759,6 +7911,18 @@ function createFailedBatchWriter(targetPath) {
     temporaryPath
   };
 }
+function writeFailedBatchRecords(targetPath, records) {
+  const writer = createFailedBatchWriter(targetPath);
+  try {
+    for (const record of records) {
+      writer.write(record);
+    }
+    writer.commit();
+  } catch (error) {
+    writer.cleanup();
+    throw error;
+  }
+}
 function* readLegacyFailedBatchRecords(filePath, options) {
   const rawData = fs2.readFileSync(filePath, "utf-8");
   const trimmed = stripLeadingBomAndWhitespace(rawData).trim();
@@ -8041,14 +8205,18 @@ function getSafeEmbeddingChunkTokenLimit(provider) {
   const maxChunkTokens = Math.max(256, Math.floor(providerMaxTokens * 0.75));
   return Math.min(2e3, maxChunkTokens);
 }
-function getDynamicBatchOptions(provider) {
-  if (provider.provider === "ollama") {
-    return {
-      maxBatchTokens: provider.modelInfo.maxTokens,
-      maxBatchItems: 1
-    };
+var DEFAULT_OLLAMA_MAX_BATCH_ITEMS = 16;
+var DEFAULT_OLLAMA_MAX_BATCH_TOKENS = 65536;
+function getDynamicBatchOptions(provider, embeddingBatch) {
+  if (provider.provider !== "ollama") {
+    return {};
   }
-  return {};
+  const base = { maxBatchTokens: DEFAULT_OLLAMA_MAX_BATCH_TOKENS, maxBatchItems: DEFAULT_OLLAMA_MAX_BATCH_ITEMS };
+  return {
+    ...base,
+    ...typeof embeddingBatch?.maxBatchTokens === "number" && Number.isFinite(embeddingBatch.maxBatchTokens) ? { maxBatchTokens: embeddingBatch.maxBatchTokens } : {},
+    ...typeof embeddingBatch?.maxBatchItems === "number" && Number.isFinite(embeddingBatch.maxBatchItems) ? { maxBatchItems: embeddingBatch.maxBatchItems } : {}
+  };
 }
 function isSqliteCorruptionError(error) {
   const message = getErrorMessage3(error).toLowerCase();
@@ -8066,6 +8234,14 @@ function getPendingChunkId(rawChunk) {
   const id = rawChunk.id;
   return typeof id === "string" ? id : null;
 }
+function parseBlameTimestamp(value, endOfDay) {
+  let timestampMs = Date.parse(value);
+  if (Number.isNaN(timestampMs)) return null;
+  if (endOfDay && /^\d{4}-\d{2}-\d{2}$/.test(value.trim())) {
+    timestampMs += 24 * 60 * 60 * 1e3 - 1;
+  }
+  return Math.floor(timestampMs / 1e3);
+}
 function metadataFromBlame(blame) {
   if (!blame) {
     return {};
@@ -8212,7 +8388,7 @@ function promoteIdentifierMatches(query, combined, semanticCandidates, keywordCa
   const remainder = combined.filter((candidate) => !promotedIds.has(candidate.id));
   return [...promoted, ...remainder];
 }
-function buildSymbolDefinitionLane(query, database, branchChunkIds, branchSymbolIds, limit, fallbackCandidates, prioritizeSourcePaths = classifyQueryIntentRaw(query) === "source") {
+function buildSymbolDefinitionLane(query, database, branchChunkIds, branchSymbolIds, limit, fallbackCandidates, prioritizeSourcePaths = classifyQueryIntentRaw(query) === "source", allowNonSourcePaths = false) {
   if (!prioritizeSourcePaths) {
     return [];
   }
@@ -8232,7 +8408,7 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, branchSymbol
     if (!isImplementationChunkType(chunkType)) {
       return false;
     }
-    if (!isLikelyImplementationPath2(chunk.filePath)) {
+    if (!allowNonSourcePaths && !isLikelyImplementationPath2(chunk.filePath)) {
       return false;
     }
     const nameLower = (chunk.name ?? "").toLowerCase();
@@ -8296,7 +8472,7 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, branchSymbol
         }
         foundCoveringChunk = upsertChunkCandidate(chunk, identifier, normalizedIdentifier) || foundCoveringChunk;
       }
-      if (foundCoveringChunk || !isLikelyImplementationPath2(symbol.filePath)) {
+      if (foundCoveringChunk || !allowNonSourcePaths && !isLikelyImplementationPath2(symbol.filePath)) {
         continue;
       }
       const symbolName = symbol.name.toLowerCase();
@@ -8350,7 +8526,7 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, branchSymbol
   const ranked = Array.from(symbolCandidates.values()).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
   if (ranked.length === 0) {
     const implementationFallback = fallbackCandidates.filter(
-      (candidate) => isImplementationChunkType(candidate.metadata.chunkType) && isLikelyImplementationPath2(candidate.metadata.filePath)
+      (candidate) => isImplementationChunkType(candidate.metadata.chunkType) && (allowNonSourcePaths || isLikelyImplementationPath2(candidate.metadata.filePath))
     );
     for (const candidate of implementationFallback) {
       const nameLower = (candidate.metadata.name ?? "").toLowerCase();
@@ -8466,10 +8642,16 @@ function matchesHardSearchFilters(candidate, options, projectRoot) {
     return false;
   }
   if (options?.blameSince) {
-    const sinceMs = Date.parse(options.blameSince);
-    if (Number.isNaN(sinceMs)) return false;
+    const since = parseBlameTimestamp(options.blameSince, false);
+    if (since === null) return false;
     const committedAt = candidate.metadata.blameCommittedAt;
-    if (committedAt === void 0 || committedAt < Math.floor(sinceMs / 1e3)) return false;
+    if (committedAt === void 0 || committedAt < since) return false;
+  }
+  if (options?.blameUntil) {
+    const until = parseBlameTimestamp(options.blameUntil, true);
+    if (until === null) return false;
+    const committedAt = candidate.metadata.blameCommittedAt;
+    if (committedAt === void 0 || committedAt > until) return false;
   }
   return true;
 }
@@ -8525,9 +8707,10 @@ var Indexer = class _Indexer {
   writerArtifactFingerprint = null;
   readerArtifactRetryAfter = /* @__PURE__ */ new Map();
   fileBatchLimits;
+  checkpointIntervalChunks;
   constructor(projectRoot, config, host, runtimeOptions = {}) {
     this.projectRoot = projectRoot;
-    this.projectIdentityHash = hashContent(this.getCanonicalPath(projectRoot)).slice(0, 16);
+    this.projectIdentityHash = this.getProjectIdentityHash(projectRoot);
     this.materializedProjectRoot = runtimeOptions.materializedProjectRoot ?? projectRoot;
     this.branchNameOverride = runtimeOptions.branchName;
     this.catalogIdentityOverride = runtimeOptions.catalogIdentity;
@@ -8537,6 +8720,7 @@ var Indexer = class _Indexer {
     this.expectedCommitOverride = runtimeOptions.expectedCommit?.toLowerCase();
     this.indexPathOverride = runtimeOptions.indexPath;
     this.fileBatchLimits = runtimeOptions.fileBatchLimits;
+    this.checkpointIntervalChunks = runtimeOptions.checkpointIntervalChunks;
     this.config = config;
     this.host = host;
     if (isGitRepo(this.materializedProjectRoot)) {
@@ -8648,6 +8832,9 @@ var Indexer = class _Indexer {
       return path15.resolve(targetPath);
     }
   }
+  getProjectIdentityHash(projectRoot) {
+    return hashContent(this.getCanonicalPath(projectRoot)).slice(0, 16);
+  }
   isProjectOwnedIndexPath() {
     return isProjectIndexPathOwnedByProject(this.projectRoot, this.indexPath, this.host);
   }
@@ -8684,7 +8871,10 @@ var Indexer = class _Indexer {
   }
   async withIndexMutationLease(operation, callback) {
     this.refreshBranchInfo();
-    const lease = acquireIndexLock(this.indexPath, operation);
+    const lease = acquireIndexLock(this.indexPath, operation, {
+      projectRoot: this.projectRoot,
+      scopedRoots: this.getScopedRoots()
+    });
     this.indexPath = lease.canonicalIndexPath;
     this.refreshRuntimeArtifactPaths();
     this.activeIndexLease = lease;
@@ -8739,6 +8929,7 @@ var Indexer = class _Indexer {
   }
   loadFileHashCache() {
     if (!(0, import_fs10.existsSync)(this.fileHashCachePath)) {
+      this.fileHashCache = /* @__PURE__ */ new Map();
       return;
     }
     try {
@@ -8778,10 +8969,10 @@ var Indexer = class _Indexer {
       invertedIndex.serialize()
     );
   }
-  getScopedRoots() {
-    const roots = /* @__PURE__ */ new Set([this.getCanonicalPath(this.projectRoot)]);
+  getScopedRoots(projectRoot = this.projectRoot) {
+    const roots = /* @__PURE__ */ new Set([this.getCanonicalPath(projectRoot)]);
     for (const kbRoot of this.config.knowledgeBases) {
-      roots.add(this.getCanonicalPath(path15.resolve(this.projectRoot, kbRoot)));
+      roots.add(this.getCanonicalPath(path15.resolve(projectRoot, kbRoot)));
     }
     return Array.from(roots);
   }
@@ -8852,14 +9043,17 @@ var Indexer = class _Indexer {
   getLegacyBranchCatalogKey() {
     return this.currentBranch || "default";
   }
-  getLegacyMigrationMetadataKey() {
-    return `index.globalBranchMigration.${this.projectIdentityHash}`;
+  getLegacyMigrationMetadataKey(projectIdentityHash = this.projectIdentityHash) {
+    return `index.globalBranchMigration.${projectIdentityHash}`;
   }
-  getProjectEmbeddingStrategyMetadataKey() {
-    return `index.embeddingStrategyVersion.${this.projectIdentityHash}`;
+  getProjectEmbeddingStrategyMetadataKey(projectIdentityHash = this.projectIdentityHash) {
+    return `index.embeddingStrategyVersion.${projectIdentityHash}`;
   }
-  getProjectForceReembedMetadataKey() {
-    return `index.forceReembed.${this.projectIdentityHash}`;
+  getProjectForceReembedMetadataKey(projectIdentityHash = this.projectIdentityHash) {
+    return `index.forceReembed.${projectIdentityHash}`;
+  }
+  getProjectMigrationFinalizedMetadataKey(projectIdentityHash = this.projectIdentityHash) {
+    return `index.migrationFinalized.${projectIdentityHash}`;
   }
   getBranchMigrationMetadataKey(prefix, catalogIdentity = this.getBranchCatalogIdentity()) {
     const branchKey = this.getBranchCatalogKeyFor(catalogIdentity);
@@ -8965,7 +9159,7 @@ var Indexer = class _Indexer {
     const legacy = this.getLegacyBranchCatalogKey();
     return primary === legacy ? [primary] : [primary, legacy];
   }
-  getProjectLocalScopedOwnershipIds(roots) {
+  getProjectLocalScopedOwnershipIds(roots, projectRoot = this.projectRoot) {
     const chunkIds = /* @__PURE__ */ new Set();
     const symbolIds = /* @__PURE__ */ new Set();
     if (!this.database) {
@@ -8973,10 +9167,10 @@ var Indexer = class _Indexer {
     }
     const projectLocalFilePaths = /* @__PURE__ */ new Set([
       ...Array.from(this.fileHashCache.keys()).filter(
-        (filePath) => this.isFileInCurrentScope(filePath, roots) && this.isFileInProjectRoot(filePath)
+        (filePath) => this.isFileInCurrentScope(filePath, roots) && this.isFileInProjectRoot(filePath, projectRoot)
       ),
       ...(this.store?.getAllMetadata() ?? []).map(({ metadata }) => metadata.filePath).filter(
-        (filePath) => this.isFileInCurrentScope(filePath, roots) && this.isFileInProjectRoot(filePath)
+        (filePath) => this.isFileInCurrentScope(filePath, roots) && this.isFileInProjectRoot(filePath, projectRoot)
       )
     ]);
     for (const filePath of projectLocalFilePaths) {
@@ -8989,15 +9183,16 @@ var Indexer = class _Indexer {
     }
     return { chunkIds, symbolIds };
   }
-  getProjectScopedBranchCatalogCleanupKeys(projectChunkIds, projectSymbolIds) {
+  getProjectScopedBranchCatalogCleanupKeys(projectChunkIds, projectSymbolIds, projectRoot = this.projectRoot) {
     if (this.config.scope !== "global") {
       return this.getBranchCatalogCleanupKeys();
     }
     const keys = /* @__PURE__ */ new Set();
     const projectChunkIdSet = new Set(projectChunkIds);
     const projectSymbolIdSet = new Set(projectSymbolIds);
+    const projectIdentityHash = this.getProjectIdentityHash(projectRoot);
     for (const branchKey of this.database?.getAllBranches() ?? []) {
-      if (branchKey.startsWith(`${this.projectIdentityHash}:`)) {
+      if (branchKey.startsWith(`${projectIdentityHash}:`)) {
         keys.add(branchKey);
         continue;
       }
@@ -9007,8 +9202,10 @@ var Indexer = class _Indexer {
         keys.add(branchKey);
       }
     }
-    for (const branchKey of this.getBranchCatalogCleanupKeys()) {
-      keys.add(branchKey);
+    if (projectRoot === this.projectRoot) {
+      for (const branchKey of this.getBranchCatalogCleanupKeys()) {
+        keys.add(branchKey);
+      }
     }
     return Array.from(keys);
   }
@@ -9016,10 +9213,10 @@ var Indexer = class _Indexer {
     const canonicalFilePath = this.getCanonicalStoredFilePath(filePath);
     return roots.some((root) => isPathWithinRoot2(canonicalFilePath, root));
   }
-  isFileInProjectRoot(filePath) {
+  isFileInProjectRoot(filePath, projectRoot = this.projectRoot) {
     return isPathWithinRoot2(
       this.getCanonicalStoredFilePath(filePath),
-      this.getCanonicalPath(this.projectRoot)
+      this.getCanonicalPath(projectRoot)
     );
   }
   clearScopedFileHashCache(roots) {
@@ -9061,12 +9258,12 @@ var Indexer = class _Indexer {
     }
     return false;
   }
-  hasForeignScopedBranchData() {
+  hasForeignScopedBranchData(projectRoot = this.projectRoot, roots = this.getScopedRoots(projectRoot)) {
     if (!this.database || this.config.scope !== "global") {
       return false;
     }
-    const roots = this.getScopedRoots();
-    const { chunkIds: projectLocalChunkIds, symbolIds: projectLocalSymbolIds } = this.getProjectLocalScopedOwnershipIds(roots);
+    const projectIdentityHash = this.getProjectIdentityHash(projectRoot);
+    const { chunkIds: projectLocalChunkIds, symbolIds: projectLocalSymbolIds } = this.getProjectLocalScopedOwnershipIds(roots, projectRoot);
     return this.database.getAllBranches().some(
       (branchKey) => {
         const branchChunkIds = this.database.getBranchChunkIds(branchKey);
@@ -9075,7 +9272,7 @@ var Indexer = class _Indexer {
         if (!hasBranchData) {
           return false;
         }
-        if (branchKey.startsWith(`${this.projectIdentityHash}:`)) {
+        if (branchKey.startsWith(`${projectIdentityHash}:`)) {
           return false;
         }
         const referencesCurrentProjectChunks = branchChunkIds.some((chunkId) => projectLocalChunkIds.has(chunkId));
@@ -9084,7 +9281,7 @@ var Indexer = class _Indexer {
       }
     );
   }
-  clearSharedIndexProjectData(store, invertedIndex, database, roots) {
+  clearSharedIndexProjectData(store, invertedIndex, database, roots, projectRoot = this.projectRoot) {
     const allMetadata = store.getAllMetadata();
     const scopedEntries = allMetadata.filter(({ metadata }) => this.isFileInCurrentScope(metadata.filePath, roots));
     const filePaths = /* @__PURE__ */ new Set([
@@ -9092,7 +9289,7 @@ var Indexer = class _Indexer {
       ...scopedEntries.map(({ metadata }) => metadata.filePath)
     ]);
     const projectLocalFilePaths = new Set(
-      Array.from(filePaths).filter((filePath) => this.isFileInProjectRoot(filePath))
+      Array.from(filePaths).filter((filePath) => this.isFileInProjectRoot(filePath, projectRoot))
     );
     const removedChunkIds = new Set(scopedEntries.map(({ key }) => key));
     for (const filePath of filePaths) {
@@ -9102,7 +9299,7 @@ var Indexer = class _Indexer {
     }
     const removedChunkIdList = Array.from(removedChunkIds);
     const projectLocalChunkIds = new Set(
-      scopedEntries.filter(({ metadata }) => this.isFileInProjectRoot(metadata.filePath)).map(({ key }) => key)
+      scopedEntries.filter(({ metadata }) => this.isFileInProjectRoot(metadata.filePath, projectRoot)).map(({ key }) => key)
     );
     for (const filePath of projectLocalFilePaths) {
       for (const chunk of database.getChunksByFile(filePath)) {
@@ -9121,7 +9318,8 @@ var Indexer = class _Indexer {
     }
     const branchCleanupKeys = this.getProjectScopedBranchCatalogCleanupKeys(
       Array.from(projectLocalChunkIds),
-      Array.from(projectLocalSymbolIds)
+      Array.from(projectLocalSymbolIds),
+      projectRoot
     );
     for (const branchKey of branchCleanupKeys) {
       database.deleteBranchChunksForBranch(branchKey, removedChunkIdList);
@@ -9156,29 +9354,96 @@ var Indexer = class _Indexer {
     database.gcOrphanSymbols();
     database.gcOrphanEmbeddings();
     database.gcOrphanChunks();
-    store.save();
     this.saveInvertedIndex(invertedIndex);
+    store.save();
     return {
       removedChunkIds: removedChunkIdList,
       hasForeignData: allMetadata.some(({ metadata }) => !this.isFileInCurrentScope(metadata.filePath, roots))
     };
   }
+  getCurrentClearRecoveryState() {
+    if (!this.configuredProviderInfo) {
+      throw new Error("Cannot persist clear recovery state before the embedding provider is initialized");
+    }
+    const compatibility = this.checkCompatibility();
+    const compatibilityDecision = compatibility.compatible ? "compatible" : compatibility.code === "EMBEDDING_STRATEGY_MISMATCH" /* EMBEDDING_STRATEGY_MISMATCH */ ? "embedding-strategy-mismatch" : "incompatible";
+    return {
+      phase: "clearing",
+      embeddingProvider: this.configuredProviderInfo.provider,
+      embeddingModel: this.configuredProviderInfo.modelInfo.model,
+      embeddingDimensions: this.configuredProviderInfo.modelInfo.dimensions,
+      embeddingStrategyVersion: EMBEDDING_STRATEGY_VERSION,
+      compatibilityDecision
+    };
+  }
+  beginClearRecoveryState() {
+    const recovery = this.getCurrentClearRecoveryState();
+    setIndexLockClearRecoveryState(this.requireActiveLease(), recovery);
+    return recovery;
+  }
+  finishClearRecoveryState() {
+    setIndexLockClearRecoveryState(this.requireActiveLease(), null);
+  }
+  matchesCurrentClearRecoveryConfiguration(recovery) {
+    const configuredProviderInfo = this.configuredProviderInfo;
+    return configuredProviderInfo !== null && recovery.embeddingProvider === configuredProviderInfo.provider && recovery.embeddingModel === configuredProviderInfo.modelInfo.model && recovery.embeddingDimensions === configuredProviderInfo.modelInfo.dimensions && recovery.embeddingStrategyVersion === EMBEDDING_STRATEGY_VERSION;
+  }
+  hasUnknownLegacyForceIndexClear(owner) {
+    return owner.operation === "force-index" && owner.clearRecovery === void 0 && owner.recoveryProtocolVersion !== 1 && (0, import_fs10.existsSync)(path15.join(this.indexPath, "force-index-phase"));
+  }
   async recoverFromInterruptedIndexingUnlocked(owners) {
     for (const owner of owners) {
       this.logger.warn("Detected interrupted indexing session, recovering...", {
         pid: owner.pid,
         hostname: owner.hostname,
         operation: owner.operation,
-        startedAt: owner.startedAt
+        startedAt: owner.startedAt,
+        projectRoot: owner.projectRoot
       });
     }
     if (this.config.scope === "global") {
-      if ((0, import_fs10.existsSync)(this.fileHashCachePath)) {
-        (0, import_fs10.unlinkSync)(this.fileHashCachePath);
+      const clearScopes = [];
+      for (const owner of owners) {
+        if (this.hasUnknownLegacyForceIndexClear(owner)) {
+          throw new Error(
+            `Cannot automatically recover interrupted force-index ${owner.token}: the legacy clearing phase ownership is unknown. The recovery marker was retained for manual inspection.`
+          );
+        }
+        if (owner.operation === "clear" && owner.clearRecovery === void 0 && owner.recoveryProtocolVersion !== 1) {
+          throw new Error(
+            `Cannot automatically recover interrupted global clear ${owner.token}: the originating recovery state is unknown. The recovery marker was retained for manual inspection.`
+          );
+        }
+        if (owner.clearRecovery === void 0) continue;
+        if (!owner.projectRoot || !owner.scopedRoots || owner.scopedRoots.length === 0) {
+          throw new Error(
+            `Cannot automatically recover interrupted global clear ${owner.token}: the originating project scope is unknown. The recovery marker was retained for manual inspection.`
+          );
+        }
+        if (!this.matchesCurrentClearRecoveryConfiguration(owner.clearRecovery)) {
+          throw new Error(
+            `Cannot automatically recover interrupted global clear ${owner.token}: the current embedding configuration does not match the originating lease. The recovery marker was retained; retry from the originating project with matching settings.`
+          );
+        }
+        clearScopes.push({
+          projectRoot: owner.projectRoot,
+          scopedRoots: owner.scopedRoots,
+          compatibilityDecision: owner.clearRecovery.compatibilityDecision
+        });
+      }
+      if (clearScopes.length > 0) {
+        this.loadFileHashCache();
+      }
+      for (const { projectRoot, scopedRoots, compatibilityDecision } of clearScopes) {
+        this.clearGlobalIndexUnlocked(projectRoot, scopedRoots, compatibilityDecision);
       }
       await this.healthCheckUnlocked();
+      this.logger.info(
+        clearScopes.length > 0 ? "Recovery complete, next index will rebuild all files" : "Recovery complete, next index will resume from the last checkpoint"
+      );
+      return;
     }
-    this.logger.info("Recovery complete, next index will re-process all files");
+    this.logger.info("Recovery complete, next index will resume from the last checkpoint");
   }
   *loadSerializedFailedBatches() {
     let warned = false;
@@ -9216,14 +9481,99 @@ var Indexer = class _Indexer {
     state.writer.write(record);
     state.recordsWritten += record.chunks.length;
   }
-  finalizeFailedBatchWriteState(state) {
+  finalizeFailedBatchWriteState(state, resolvedChunkIds = /* @__PURE__ */ new Set()) {
     if (state.recordsWritten > 0) {
-      state.writer.commit();
+      const seenChunkIds = /* @__PURE__ */ new Set();
+      const retained = [];
+      const records = Array.from(readFailedBatchRecords(state.writer.temporaryPath));
+      for (let i = records.length - 1; i >= 0; i--) {
+        const chunks = records[i].chunks.filter((rawChunk) => {
+          const chunkId = getPendingChunkId(rawChunk);
+          if (chunkId !== null) {
+            if (resolvedChunkIds.has(chunkId)) return false;
+            if (seenChunkIds.has(chunkId)) return false;
+            seenChunkIds.add(chunkId);
+          }
+          return true;
+        });
+        if (chunks.length > 0) {
+          retained.unshift({ ...records[i], chunks });
+        }
+      }
+      state.writer.cleanup();
+      if (retained.length > 0) {
+        writeFailedBatchRecords(this.failedBatchesPath, retained);
+      } else {
+        writeFailedBatchRecords(this.failedBatchesPath, []);
+        this.clearFailedBatchState();
+      }
       return;
     }
-    state.writer.cleanup();
+    state.writer.commit();
     this.clearFailedBatchState();
   }
+  getCheckpointIntervalChunks(totalChunks) {
+    return Math.max(
+      this.checkpointIntervalChunks ?? 2e3,
+      Math.floor(totalChunks / 10)
+    );
+  }
+  checkpointIndexRun(database, store, invertedIndex, failedProcessing, resolvedRetryChunkIds, currentFileHashes, committedFilePaths, scopedRoots, configuredProviderInfo) {
+    if (!this.hasProjectForceReembedPending()) {
+      this.saveIndexMetadata(configuredProviderInfo);
+      this.indexCompatibility = { compatible: true };
+    }
+    database.commitWriteTransaction();
+    database.beginWriteTransaction();
+    this.saveInvertedIndex(invertedIndex);
+    store.save();
+    if (failedProcessing.state.recordsWritten > 0 || failedProcessing.latestById.size > 0 || failedProcessing.discardedExistingRecords) {
+      for (const metadata of failedProcessing.latestById.values()) {
+        const alreadyMaterialized = metadata.chunks.some((rawChunk) => {
+          const chunkId = getPendingChunkId(rawChunk);
+          return chunkId !== null && failedProcessing.materializedRetryIds.has(chunkId);
+        });
+        if (alreadyMaterialized) continue;
+        this.writeFailedBatchRecord(failedProcessing.state, {
+          chunks: metadata.chunks,
+          attemptCount: metadata.attemptCount,
+          error: metadata.error,
+          lastAttempt: metadata.lastAttempt
+        });
+        for (const rawChunk of metadata.chunks) {
+          const chunkId = getPendingChunkId(rawChunk);
+          if (chunkId !== null) {
+            failedProcessing.materializedRetryIds.add(chunkId);
+          }
+        }
+      }
+      this.finalizeFailedBatchWriteState(failedProcessing.state, resolvedRetryChunkIds);
+      failedProcessing.state = this.createFailedBatchWriteState();
+      failedProcessing.discardedExistingRecords = false;
+      for (const record of this.loadSerializedFailedBatches()) {
+        for (const rawChunk of record.chunks) {
+          const chunkId = getPendingChunkId(rawChunk);
+          this.writeFailedBatchRecord(failedProcessing.state, { ...record, chunks: [rawChunk] });
+          if (chunkId !== null) {
+            failedProcessing.materializedRetryIds.add(chunkId);
+          }
+        }
+      }
+    }
+    const partialHashes = /* @__PURE__ */ new Map();
+    for (const filePath of committedFilePaths) {
+      const hash = currentFileHashes.get(filePath);
+      if (hash !== void 0) {
+        partialHashes.set(filePath, hash);
+      }
+    }
+    if (scopedRoots) {
+      this.replaceScopedFileHashCache(partialHashes, scopedRoots);
+    } else {
+      this.fileHashCache = partialHashes;
+      this.saveFileHashCache();
+    }
+  }
   clearFailedBatchState() {
     if ((0, import_fs10.existsSync)(this.failedBatchesPath)) {
       try {
@@ -9250,6 +9600,7 @@ var Indexer = class _Indexer {
   prepareFailedBatchProcessing(roots, shouldProcess) {
     const state = this.createFailedBatchWriteState();
     const latestById = /* @__PURE__ */ new Map();
+    let discardedExistingRecords = false;
     try {
       for (const batch of this.loadSerializedFailedBatches()) {
         for (const rawChunk of batch.chunks) {
@@ -9260,10 +9611,12 @@ var Indexer = class _Indexer {
             continue;
           }
           if (!shouldProcess(filePath)) {
+            discardedExistingRecords = true;
             continue;
           }
           const chunkId = getPendingChunkId(rawChunk);
           if (!chunkId) {
+            discardedExistingRecords = true;
             continue;
           }
           const existing = latestById.get(chunkId);
@@ -9271,12 +9624,18 @@ var Indexer = class _Indexer {
             latestById.set(chunkId, {
               attemptCount: batch.attemptCount,
               error: batch.error,
-              lastAttempt: batch.lastAttempt
+              lastAttempt: batch.lastAttempt,
+              chunks: [rawChunk]
             });
           }
         }
       }
-      return { state, latestById };
+      return {
+        state,
+        latestById,
+        materializedRetryIds: /* @__PURE__ */ new Set(),
+        discardedExistingRecords
+      };
     } catch (error) {
       state.writer.cleanup();
       throw error;
@@ -9312,10 +9671,34 @@ var Indexer = class _Indexer {
       }
     }
   }
+  restoreMissingChunkRows(database, chunks) {
+    const missing = [];
+    for (const chunk of chunks) {
+      if (database.getChunk(chunk.id)) {
+        continue;
+      }
+      missing.push({
+        chunkId: chunk.id,
+        contentHash: chunk.contentHash,
+        filePath: chunk.metadata.filePath,
+        startLine: chunk.metadata.startLine,
+        endLine: chunk.metadata.endLine,
+        nodeType: chunk.metadata.chunkType,
+        name: chunk.metadata.name,
+        language: chunk.metadata.language,
+        blameSha: chunk.metadata.blameSha,
+        blameAuthor: chunk.metadata.blameAuthor,
+        blameAuthorEmail: chunk.metadata.blameAuthorEmail,
+        blameCommittedAt: chunk.metadata.blameCommittedAt,
+        blameSummary: chunk.metadata.blameSummary
+      });
+    }
+    if (missing.length > 0) {
+      database.upsertChunksBatch(missing);
+    }
+  }
   getProviderRateLimits(provider) {
     switch (provider) {
-      case "github-copilot":
-        return { concurrency: 1, intervalMs: 4e3, minRetryMs: 5e3, maxRetryMs: 6e4 };
       case "openai":
         return { concurrency: 3, intervalMs: 500, minRetryMs: 1e3, maxRetryMs: 3e4 };
       case "google":
@@ -9384,10 +9767,11 @@ var Indexer = class _Indexer {
     const embeddingPartsByChunk = /* @__PURE__ */ new Map();
     const completedVectorsByChunkId = /* @__PURE__ */ new Map();
     const completedChunkIds = /* @__PURE__ */ new Set();
-    const requestBatches = createPendingEmbeddingRequestBatches(
-      chunksNeedingEmbedding,
-      getDynamicBatchOptions(options.configuredProviderInfo)
-    );
+    const batchOptions = getDynamicBatchOptions(options.configuredProviderInfo, this.config.embedding?.batch);
+    if (options.forceSingleItemBatches && options.configuredProviderInfo.provider === "ollama") {
+      batchOptions.maxBatchItems = 1;
+    }
+    const requestBatches = createPendingEmbeddingRequestBatches(chunksNeedingEmbedding, batchOptions);
     let fatalError;
     for (const requestBatch of requestBatches) {
       await options.queue.onSizeLessThan(Math.max(1, options.providerRateLimits.concurrency));
@@ -9950,7 +10334,7 @@ var Indexer = class _Indexer {
     }
     if (!this.configuredProviderInfo) {
       throw new Error(
-        "No embedding provider available. Configure GitHub Copilot, OpenAI, Google, Ollama, or a custom OpenAI-compatible endpoint."
+        "No embedding provider available. Configure OpenAI, Google, Ollama, or a custom OpenAI-compatible endpoint."
       );
     }
     this.logger.info("Initializing indexer", {
@@ -9981,7 +10365,20 @@ var Indexer = class _Indexer {
         ]);
       }
       if (recoveredOwners.length > 0 && this.config.scope === "project") {
-        await this.resetLocalIndexArtifacts();
+        const unknownLegacyForceIndex = recoveredOwners.find(
+          (owner) => this.hasUnknownLegacyForceIndexClear(owner)
+        );
+        if (unknownLegacyForceIndex) {
+          throw new Error(
+            `Cannot automatically recover interrupted force-index ${unknownLegacyForceIndex.token}: the legacy clearing phase ownership is unknown. The recovery marker was retained for manual inspection.`
+          );
+        }
+        const shouldReset = recoveredOwners.some(
+          (owner) => owner.clearRecovery !== void 0 || owner.operation === "clear" && owner.recoveryProtocolVersion !== 1
+        );
+        if (shouldReset) {
+          await this.resetLocalIndexArtifacts();
+        }
       }
       this.store = new VectorStore(storePath, dimensions);
       if ((0, import_fs10.existsSync)(storePath) || (0, import_fs10.existsSync)(vectorMetadataPath)) {
@@ -10497,6 +10894,70 @@ var Indexer = class _Indexer {
     );
     return createCostEstimate(files, configuredProviderInfo);
   }
+  // Dry-run counterpart to index()/forceIndex(): parse the real file set and sum
+  // estimateTokens over the embedding text of every indexable chunk, without
+  // calling the embedding provider or writing to the index. Read-only and
+  // lock-free (mirrors estimateCost). The token sum is the exact value "Tokens
+  // used" climbs to for a force index (cache bypassed); for an incremental it is
+  // an upper bound because cached chunks are counted here but not re-embedded.
+  // Used by index_codebase(dryRun:true) to give a stable, monotonic progress
+  // denominator that matches the live "Tokens used" basis.
+  async dryRunCost() {
+    const { configuredProviderInfo } = await this.ensureInitialized();
+    const maxChunkTokens = getSafeEmbeddingChunkTokenLimit(configuredProviderInfo);
+    const includePatterns = [...this.config.include, ...this.config.additionalInclude];
+    const { files } = await collectFiles(
+      this.materializedProjectRoot,
+      includePatterns,
+      this.config.exclude,
+      this.config.indexing.maxFileSize,
+      this.getMaterializedKnowledgeBases(),
+      { maxDepth: this.config.indexing.maxDepth, maxFilesPerDirectory: this.config.indexing.maxFilesPerDirectory }
+    );
+    let filesCount = 0;
+    let chunksCount = 0;
+    let tokensToEmbed = 0;
+    for (const batch of iterateOrderedFileBatches(files, (f) => f.size, this.fileBatchLimits)) {
+      const loadedFiles = await Promise.all(batch.map(async (f) => {
+        try {
+          return {
+            path: this.toStoredFilePath(f.path),
+            content: await import_fs10.promises.readFile(f.path, "utf-8")
+          };
+        } catch {
+          return null;
+        }
+      }));
+      const readable = loadedFiles.filter(
+        (f) => f !== null
+      );
+      filesCount += readable.length;
+      const contentByPath = new Map(readable.map((f) => [f.path, f.content]));
+      const parsedFiles = parseFiles(readable, this.config.indexing.linesPerChunk);
+      for (const parsed of parsedFiles) {
+        let chunksToProcess = parsed.chunks;
+        if (this.config.indexing.fallbackToTextOnMaxChunks && chunksToProcess.length > this.config.indexing.maxChunksPerFile) {
+          const content = contentByPath.get(parsed.path);
+          if (content !== void 0) {
+            chunksToProcess = parseFileAsText(parsed.path, content, this.config.indexing.linesPerChunk);
+          }
+        }
+        chunksToProcess = selectIndexableChunks(
+          chunksToProcess,
+          this.config.indexing.maxChunksPerFile,
+          this.config.indexing.semanticOnly
+        );
+        for (const chunk of chunksToProcess) {
+          const texts = createEmbeddingTexts(chunk, parsed.path, maxChunkTokens);
+          chunksCount += 1;
+          for (const text of texts) {
+            tokensToEmbed += estimateTokens2(text);
+          }
+        }
+      }
+    }
+    return { filesCount, chunksCount, tokensToEmbed };
+  }
   async index(onProgress) {
     return this.withIndexMutationLease("index", async (recoveredOwners) => {
       return this.indexUnlocked(onProgress, recoveredOwners);
@@ -10617,7 +11078,17 @@ var Indexer = class _Indexer {
     const needsCallGraphResolutionMigration = database.getMetadata(this.getCallGraphResolutionMetadataKey()) !== CALL_GRAPH_RESOLUTION_VERSION;
     for (const file of files) {
       const storedPath = this.toStoredFilePath(file.path);
-      const currentHash = hashFile(file.path);
+      let currentHash;
+      try {
+        currentHash = hashFile(file.path);
+      } catch (error) {
+        stats.skippedFiles.push({ path: this.toCanonicalFilePath(file.path), reason: "unreadable" });
+        this.logger.warn("Skipped unreadable file during indexing", {
+          path: file.path,
+          error: getErrorMessage3(error)
+        });
+        continue;
+      }
       currentFileHashes.set(storedPath, currentHash);
       const cachedHashMatches = this.fileHashCache.get(storedPath) === currentHash;
       const needsCallGraphRefresh = cachedHashMatches && needsCallGraphResolutionMigration && database.getChunksByFile(storedPath).some(
@@ -10625,7 +11096,8 @@ var Indexer = class _Indexer {
       );
       const requiresSwiftParserUpgrade = reparseCachedSwiftFiles && path15.extname(storedPath).toLowerCase() === ".swift";
       const requiresMetalParserUpgrade = reparseCachedMetalFiles && path15.extname(storedPath).toLowerCase() === ".metal";
-      if (cachedHashMatches && !needsCallGraphRefresh && !requiresSwiftParserUpgrade && !requiresMetalParserUpgrade && !refreshCachedSymbols) {
+      const inMigrationScope = forceScopedReembed && scopedRoots !== null && this.isFileInCurrentScope(storedPath, scopedRoots);
+      if (cachedHashMatches && !inMigrationScope && !needsCallGraphRefresh && !requiresSwiftParserUpgrade && !requiresMetalParserUpgrade && !refreshCachedSymbols) {
         unchangedFilePaths.add(storedPath);
         this.logger.recordCacheHit();
       } else {
@@ -10751,6 +11223,9 @@ var Indexer = class _Indexer {
         }
       }
       let processedChangedFiles = 0;
+      let lastCheckpointChunks = 0;
+      const committedFilePaths = new Set(unchangedFilePaths);
+      const resolvedRetryChunkIds = /* @__PURE__ */ new Set();
       for (const descriptorBatch of iterateOrderedFileBatches(
         changedFileDescriptors,
         (descriptor) => descriptor.sourceBytes,
@@ -10764,7 +11239,7 @@ var Indexer = class _Indexer {
         const loadedByPath = new Map(loadedFiles.map((file) => [file.path, file]));
         const descriptorByPath = new Map(descriptorBatch.map((descriptor) => [descriptor.storedPath, descriptor]));
         const parseStartTime = import_perf_hooks.performance.now();
-        const parsedFiles = parseFiles(loadedFiles);
+        const parsedFiles = parseFiles(loadedFiles, this.config.indexing.linesPerChunk);
         const parseMs = import_perf_hooks.performance.now() - parseStartTime;
         this.logger.recordFilesParsed(parsedFiles.length);
         this.logger.recordParseDuration(parseMs);
@@ -10787,7 +11262,7 @@ var Indexer = class _Indexer {
           }
           let chunksToProcess = parsed.chunks;
           if (this.config.indexing.fallbackToTextOnMaxChunks && chunksToProcess.length > this.config.indexing.maxChunksPerFile) {
-            chunksToProcess = parseFileAsText(parsed.path, loadedFile.content);
+            chunksToProcess = parseFileAsText(parsed.path, loadedFile.content, this.config.indexing.linesPerChunk);
           }
           chunksToProcess = selectIndexableChunks(
             chunksToProcess,
@@ -10921,6 +11396,10 @@ var Indexer = class _Indexer {
         }
         if (symbolBatch.length > 0) {
           database.upsertSymbolsBatch(symbolBatch);
+          database.addSymbolsToBranchBatch(
+            this.getBranchCatalogKey(),
+            symbolBatch.map((symbol) => symbol.id)
+          );
         }
         if (edgeBatch.length > 0) {
           database.upsertCallEdgesBatch(edgeBatch);
@@ -10956,6 +11435,12 @@ var Indexer = class _Indexer {
             forceReembed: forceScopedReembed,
             reuseCachedEmbeddings: true,
             incrementRepeatedFailures: true,
+            onSucceeded: (succeededChunks) => {
+              database.addChunksToBranchBatch(
+                this.getBranchCatalogKey(),
+                succeededChunks.map((chunk) => chunk.id)
+              );
+            },
             onProgress: (batchProgress) => onProgress?.({
               phase: "embedding",
               filesProcessed: unchangedFilePaths.size + processedChangedFiles,
@@ -10974,6 +11459,27 @@ var Indexer = class _Indexer {
             }
           }
         }
+        for (const descriptor of descriptorBatch) {
+          const existingFileChunks = existingChunksByFile.get(descriptor.storedPath);
+          if (!existingFileChunks || existingFileChunks.size === 0) {
+            committedFilePaths.add(descriptor.storedPath);
+          }
+        }
+        const checkpointInterval = this.getCheckpointIntervalChunks(stats.totalChunks);
+        if (stats.totalChunks - lastCheckpointChunks >= checkpointInterval) {
+          lastCheckpointChunks = stats.totalChunks;
+          this.checkpointIndexRun(
+            database,
+            store,
+            invertedIndex,
+            failedProcessing,
+            resolvedRetryChunkIds,
+            currentFileHashes,
+            committedFilePaths,
+            scopedRoots,
+            configuredProviderInfo
+          );
+        }
       }
       const retryableFailedChunks = this.iterateLatestFailedChunks(
         failedProcessing.latestById,
@@ -10994,6 +11500,7 @@ var Indexer = class _Indexer {
             retryableChunksWithExistingData.add(chunk.id);
           }
         }
+        this.restoreMissingChunkRows(database, pendingChunks);
         stats.totalChunks += pendingChunks.length;
         onProgress?.({
           phase: "embedding",
@@ -11016,6 +11523,17 @@ var Indexer = class _Indexer {
           forceReembed: forceScopedReembed,
           reuseCachedEmbeddings: true,
           incrementRepeatedFailures: true,
+          forceSingleItemBatches: true,
+          onSucceeded: (succeededChunks) => {
+            database.addChunksToBranchBatch(
+              this.getBranchCatalogKey(),
+              succeededChunks.map((chunk) => chunk.id)
+            );
+            for (const chunk of succeededChunks) {
+              failedProcessing.latestById.delete(chunk.id);
+              resolvedRetryChunkIds.add(chunk.id);
+            }
+          },
           onProgress: (batchProgress) => onProgress?.({
             phase: "embedding",
             filesProcessed: files.length,
@@ -11033,6 +11551,20 @@ var Indexer = class _Indexer {
             failedForcedChunkIds.add(chunkId);
           }
         }
+        if (stats.totalChunks - lastCheckpointChunks >= this.getCheckpointIntervalChunks(stats.totalChunks)) {
+          lastCheckpointChunks = stats.totalChunks;
+          this.checkpointIndexRun(
+            database,
+            store,
+            invertedIndex,
+            failedProcessing,
+            resolvedRetryChunkIds,
+            currentFileHashes,
+            committedFilePaths,
+            scopedRoots,
+            configuredProviderInfo
+          );
+        }
       }
       const removedChunkIds = [];
       for (const [chunkId] of existingChunks) {
@@ -11069,13 +11601,6 @@ var Indexer = class _Indexer {
         if (removedStoredChunks) {
           this.saveInvertedIndex(invertedIndex);
         }
-        if (scopedRoots) {
-          this.replaceScopedFileHashCache(currentFileHashes, scopedRoots);
-        } else {
-          this.fileHashCache = currentFileHashes;
-          this.saveFileHashCache();
-        }
-        this.finalizeFailedBatchWriteState(failedProcessing.state);
         database.setMetadata(swiftParserMetadataKey, SWIFT_PARSER_VERSION);
         database.setMetadata(metalParserMetadataKey, METAL_PARSER_VERSION);
         database.setMetadata(symbolExtractorMetadataKey, SYMBOL_EXTRACTOR_VERSION);
@@ -11084,6 +11609,13 @@ var Indexer = class _Indexer {
         this.indexCompatibility = { compatible: true };
         database.commitWriteTransaction();
         writeTransactionActive = false;
+        this.finalizeFailedBatchWriteState(failedProcessing.state, resolvedRetryChunkIds);
+        if (scopedRoots) {
+          this.replaceScopedFileHashCache(currentFileHashes, scopedRoots);
+        } else {
+          this.fileHashCache = currentFileHashes;
+          this.saveFileHashCache();
+        }
         stats.durationMs = Date.now() - startTime;
         onProgress?.({
           phase: "complete",
@@ -11107,13 +11639,6 @@ var Indexer = class _Indexer {
         );
         store.save();
         this.saveInvertedIndex(invertedIndex);
-        if (scopedRoots) {
-          this.replaceScopedFileHashCache(currentFileHashes, scopedRoots);
-        } else {
-          this.fileHashCache = currentFileHashes;
-          this.saveFileHashCache();
-        }
-        this.finalizeFailedBatchWriteState(failedProcessing.state);
         database.setMetadata(swiftParserMetadataKey, SWIFT_PARSER_VERSION);
         database.setMetadata(metalParserMetadataKey, METAL_PARSER_VERSION);
         database.setMetadata(symbolExtractorMetadataKey, SYMBOL_EXTRACTOR_VERSION);
@@ -11122,6 +11647,13 @@ var Indexer = class _Indexer {
         this.indexCompatibility = { compatible: true };
         database.commitWriteTransaction();
         writeTransactionActive = false;
+        this.finalizeFailedBatchWriteState(failedProcessing.state, resolvedRetryChunkIds);
+        if (scopedRoots) {
+          this.replaceScopedFileHashCache(currentFileHashes, scopedRoots);
+        } else {
+          this.fileHashCache = currentFileHashes;
+          this.saveFileHashCache();
+        }
         stats.durationMs = Date.now() - startTime;
         onProgress?.({
           phase: "complete",
@@ -11156,15 +11688,15 @@ var Indexer = class _Indexer {
       );
       store.save();
       this.saveInvertedIndex(invertedIndex);
+      database.commitWriteTransaction();
+      writeTransactionActive = false;
+      this.finalizeFailedBatchWriteState(failedProcessing.state, resolvedRetryChunkIds);
       if (scopedRoots) {
         this.replaceScopedFileHashCache(currentFileHashes, scopedRoots);
       } else {
         this.fileHashCache = currentFileHashes;
         this.saveFileHashCache();
       }
-      this.finalizeFailedBatchWriteState(failedProcessing.state);
-      database.commitWriteTransaction();
-      writeTransactionActive = false;
       if (this.config.indexing.autoGc && stats.removedChunks > 0) {
         const gcReset = await this.maybeRunOrphanGc();
         if (gcReset) {
@@ -11188,6 +11720,9 @@ var Indexer = class _Indexer {
       if (forceScopedReembed && failedForcedChunkIds.size === 0) {
         database.deleteMetadata(this.getProjectForceReembedMetadataKey());
       }
+      if (forceScopedReembed) {
+        database.setMetadata(this.getProjectMigrationFinalizedMetadataKey(), "true");
+      }
       database.setMetadata(swiftParserMetadataKey, SWIFT_PARSER_VERSION);
       database.setMetadata(metalParserMetadataKey, METAL_PARSER_VERSION);
       database.setMetadata(symbolExtractorMetadataKey, SYMBOL_EXTRACTOR_VERSION);
@@ -11298,26 +11833,41 @@ var Indexer = class _Indexer {
       shouldPrefilterByBranch: branchChunkIds !== null && (this.config.scope === "global" || hasInitializedBranchCatalog)
     };
   }
-  searchCandidatesWithBranchPrefilter(initialLimit, totalCount, branchChunkIds, shouldPrefilterByBranch, search, getChunkId) {
+  searchCandidatesWithAllowedIds(initialLimit, totalCount, allowedChunkIds, shouldPrefilter, search, getChunkId) {
     const normalizedLimit = Math.max(0, Math.floor(initialLimit));
     if (normalizedLimit === 0) return [];
-    if (!shouldPrefilterByBranch || !branchChunkIds) {
+    if (!shouldPrefilter || !allowedChunkIds) {
       return search(normalizedLimit);
     }
-    const targetCount = Math.min(normalizedLimit, branchChunkIds.size);
+    const targetCount = Math.min(normalizedLimit, allowedChunkIds.size);
     if (targetCount === 0 || totalCount === 0) return [];
     let requestedLimit = Math.min(normalizedLimit, totalCount);
     while (true) {
       const results = search(requestedLimit);
-      const branchResults = results.filter((candidate) => branchChunkIds.has(getChunkId(candidate)));
-      if (branchResults.length >= targetCount || results.length < requestedLimit || requestedLimit >= totalCount) {
-        return branchResults;
+      const allowedResults = results.filter((candidate) => allowedChunkIds.has(getChunkId(candidate)));
+      if (allowedResults.length >= targetCount || results.length < requestedLimit || requestedLimit >= totalCount) {
+        return allowedResults;
       }
       const nextLimit = Math.min(totalCount, Math.max(requestedLimit + 1, requestedLimit * 2));
-      if (nextLimit === requestedLimit) return branchResults;
+      if (nextLimit === requestedLimit) return allowedResults;
       requestedLimit = nextLimit;
     }
   }
+  getTemporalChunkIds(database, options) {
+    if (!options?.blameSince && !options?.blameUntil) return null;
+    const since = options.blameSince ? parseBlameTimestamp(options.blameSince, false) : void 0;
+    const until = options.blameUntil ? parseBlameTimestamp(options.blameUntil, true) : void 0;
+    if (since === null || until === null) {
+      return /* @__PURE__ */ new Set();
+    }
+    return new Set(database.getChunkIdsByBlameDate(since, until));
+  }
+  intersectChunkIdSets(first, second) {
+    if (first === null) return second;
+    if (second === null) return first;
+    const [smaller, larger] = first.size <= second.size ? [first, second] : [second, first];
+    return new Set(Array.from(smaller).filter((chunkId) => larger.has(chunkId)));
+  }
   buildCandidateSnapshot(candidate) {
     return {
       id: candidate.id,
@@ -11332,13 +11882,16 @@ var Indexer = class _Indexer {
   buildCandidateSnapshotList(candidates) {
     return candidates.map((candidate) => this.buildCandidateSnapshot(candidate));
   }
-  searchSemanticCandidates(store, embedding, initialLimit, branchChunkIds, shouldPrefilterByBranch) {
-    return this.searchCandidatesWithBranchPrefilter(
-      initialLimit,
-      store.count(),
+  searchSemanticCandidates(store, embedding, initialLimit, branchChunkIds, shouldPrefilterByBranch, temporalChunkIds) {
+    const availableCount = temporalChunkIds?.size ?? store.count();
+    if (availableCount === 0) return [];
+    const allowedIds = temporalChunkIds === null ? void 0 : Array.from(temporalChunkIds);
+    return this.searchCandidatesWithAllowedIds(
+      Math.min(initialLimit, availableCount),
+      availableCount,
       branchChunkIds,
       shouldPrefilterByBranch,
-      (requestedLimit) => store.search(embedding, requestedLimit),
+      (requestedLimit) => store.search(embedding, requestedLimit, allowedIds),
       (candidate) => candidate.id
     );
   }
@@ -11363,8 +11916,9 @@ var Indexer = class _Indexer {
     const rerankTopN = this.config.search.rerankTopN;
     const filterByBranch = options?.filterByBranch ?? true;
     const sourceIntent = options?.definitionIntent === true || classifyQueryIntentRaw(query) === "source";
+    const prioritizeSourcePaths = sourceIntent || options?.prioritizeSourcePaths === true;
     const identifierHints = extractIdentifierHints(query);
-    const candidateLimit = maxResults * (sourceIntent ? 12 : 4);
+    const candidateLimit = maxResults * (prioritizeSourcePaths ? 12 : 4);
     this.logger.search("debug", "Starting search", {
       query,
       maxResults,
@@ -11395,6 +11949,7 @@ var Indexer = class _Indexer {
       branchChunkIds = new Set(branchCatalogKeys.flatMap((branchKey) => database.getBranchChunkIds(branchKey)));
       branchSymbolIds = new Set(branchCatalogKeys.flatMap((branchKey) => database.getBranchSymbolIds(branchKey)));
     }
+    const temporalChunkIds = this.getTemporalChunkIds(database, options);
     const { hasInitializedBranchCatalog, shouldPrefilterByBranch } = this.getBranchPrefilterState(database, branchChunkIds);
     const prefilterMs = import_perf_hooks.performance.now() - prefilterStartTime;
     const vectorStartTime = import_perf_hooks.performance.now();
@@ -11403,7 +11958,8 @@ var Indexer = class _Indexer {
       embedding,
       candidateLimit,
       branchChunkIds,
-      shouldPrefilterByBranch
+      shouldPrefilterByBranch,
+      temporalChunkIds
     ) : [];
     const vectorMs = import_perf_hooks.performance.now() - vectorStartTime;
     const keywordStartTime = import_perf_hooks.performance.now();
@@ -11413,7 +11969,8 @@ var Indexer = class _Indexer {
       store,
       invertedIndex,
       branchChunkIds,
-      shouldPrefilterByBranch
+      shouldPrefilterByBranch,
+      temporalChunkIds
     );
     const keywordMs = import_perf_hooks.performance.now() - keywordStartTime;
     const scopedSemanticCandidates = semanticCandidates.filter(
@@ -11435,7 +11992,7 @@ var Indexer = class _Indexer {
       rerankTopN,
       limit: maxResults,
       hybridWeight: rankingHybridWeight,
-      prioritizeSourcePaths: sourceIntent
+      prioritizeSourcePaths
     });
     const rerankedCombined = await this.rerankCandidatesWithApi(query, combined, {
       definitionIntent: options?.definitionIntent === true,
@@ -11471,10 +12028,11 @@ var Indexer = class _Indexer {
       branchSymbolIds,
       maxResults,
       union,
-      sourceIntent
+      sourceIntent,
+      options?.definitionIntent === true && ((options.directory?.trim().length ?? 0) > 0 || (options.fileType?.trim().length ?? 0) > 0)
     );
     const prePrimaryLane = mergeTieredResults(deterministicIdentifierLane, identifierLane, maxResults * 4);
-    const primaryLane = mergeTieredResults(prePrimaryLane, symbolLane, maxResults * 4);
+    const primaryLane = options?.definitionIntent === true ? mergeTieredResults(symbolLane, prePrimaryLane, maxResults * 4) : mergeTieredResults(prePrimaryLane, symbolLane, maxResults * 4);
     const tiered = mergeTieredResults(primaryLane, rescued, maxResults * 4);
     const hasCodeHints = extractCodeTermHints(query).length > 0 || identifierHints.length > 0;
     const baseFiltered = tiered.filter(
@@ -11569,14 +12127,18 @@ var Indexer = class _Indexer {
       })
     );
   }
-  async keywordSearch(query, limit, store, invertedIndex, branchChunkIds = null, shouldPrefilterByBranch = false) {
+  async keywordSearch(query, limit, store, invertedIndex, branchChunkIds = null, shouldPrefilterByBranch = false, temporalChunkIds = null) {
     const normalizedLimit = Math.max(0, Math.floor(limit));
     if (normalizedLimit === 0) return [];
-    const scoreEntries = this.searchCandidatesWithBranchPrefilter(
+    const allowedChunkIds = this.intersectChunkIdSets(
+      shouldPrefilterByBranch ? branchChunkIds : null,
+      temporalChunkIds
+    );
+    const scoreEntries = this.searchCandidatesWithAllowedIds(
       normalizedLimit,
       invertedIndex.getDocumentCount(),
-      branchChunkIds,
-      shouldPrefilterByBranch,
+      allowedChunkIds,
+      allowedChunkIds !== null,
       (requestedLimit) => Array.from(invertedIndex.search(query, requestedLimit)),
       ([chunkId]) => chunkId
     );
@@ -11661,7 +12223,17 @@ var Indexer = class _Indexer {
     );
     const currentFileHashes = /* @__PURE__ */ new Map();
     for (const file of files) {
-      currentFileHashes.set(this.toStoredFilePath(file.path), hashFile(file.path));
+      let hash;
+      try {
+        hash = hashFile(file.path);
+      } catch (error) {
+        this.logger.warn("Skipped unreadable file during freshness check", {
+          path: file.path,
+          error: getErrorMessage3(error)
+        });
+        return { readable: false, current: false, reason: "unreadable" };
+      }
+      currentFileHashes.set(this.toStoredFilePath(file.path), hash);
     }
     const scopedRoots = this.config.scope === "global" ? this.getScopedRoots() : null;
     const cachedFileHashes = scopedRoots ? new Map(Array.from(this.fileHashCache).filter(([filePath]) => this.isFileInCurrentScope(filePath, scopedRoots))) : this.fileHashCache;
@@ -11687,69 +12259,87 @@ var Indexer = class _Indexer {
   async forceIndex(onProgress) {
     return this.withIndexMutationLease("force-index", async (recoveredOwners) => {
       await this.ensureInitializedUnlocked(recoveredOwners);
-      await this.clearIndexUnlocked();
+      const recovery = this.beginClearRecoveryState();
+      await this.clearIndexUnlocked(recovery.compatibilityDecision);
+      this.finishClearRecoveryState();
       return this.indexUnlocked(onProgress, [], true);
     });
   }
   async clearIndex() {
     await this.withIndexMutationLease("clear", async (recoveredOwners) => {
       await this.ensureInitializedUnlocked(recoveredOwners);
-      await this.clearIndexUnlocked();
+      const recovery = this.beginClearRecoveryState();
+      await this.clearIndexUnlocked(recovery.compatibilityDecision);
     });
   }
-  async clearIndexUnlocked() {
+  clearGlobalIndexDataUnlocked(projectRoot = this.projectRoot) {
     const { store, invertedIndex, database } = this.requireLoadedIndexState();
-    if (this.config.scope === "global") {
-      store.load();
-      invertedIndex.load();
-      this.loadFileHashCache();
-      const roots = this.getScopedRoots();
-      const compatibility = this.checkCompatibility();
-      const allMetadata = store.getAllMetadata();
-      const hasForeignData = allMetadata.some(({ metadata }) => !this.isFileInCurrentScope(metadata.filePath, roots)) || this.hasForeignScopedBranchData() || this.hasForeignScopedFileHashData(roots) || this.hasForeignScopedFailedBatches(roots);
-      if (!compatibility.compatible && hasForeignData) {
-        if (compatibility.code === "EMBEDDING_STRATEGY_MISMATCH" /* EMBEDDING_STRATEGY_MISMATCH */) {
-          this.clearSharedIndexProjectData(store, invertedIndex, database, roots);
-          this.clearScopedFileHashCache(roots);
-          this.clearScopedFailedBatches(roots);
-          database.setMetadata(this.getProjectForceReembedMetadataKey(), "true");
-          database.deleteMetadata(this.getProjectEmbeddingStrategyMetadataKey());
+    const clearedBranchKeys = database.getAllBranches();
+    store.clear();
+    store.save();
+    invertedIndex.clear();
+    this.saveInvertedIndex(invertedIndex);
+    this.fileHashCache.clear();
+    this.saveFileHashCache();
+    database.clearAllIndexedData();
+    this.deleteBranchCommitMetadata(database, clearedBranchKeys);
+    this.clearFailedBatchState();
+    database.deleteMetadata("index.version");
+    database.deleteMetadata("index.pathStorageVersion");
+    database.deleteMetadata("index.embeddingProvider");
+    database.deleteMetadata("index.embeddingModel");
+    database.deleteMetadata("index.embeddingDimensions");
+    database.deleteMetadata("index.embeddingStrategyVersion");
+    const projectIdentityHash = this.getProjectIdentityHash(projectRoot);
+    database.deleteMetadata(this.getProjectEmbeddingStrategyMetadataKey(projectIdentityHash));
+    database.deleteMetadata(this.getProjectForceReembedMetadataKey(projectIdentityHash));
+    database.deleteMetadata(this.getLegacyMigrationMetadataKey(projectIdentityHash));
+    database.deleteMetadata("index.createdAt");
+    database.deleteMetadata("index.updatedAt");
+    this.indexCompatibility = this.validateIndexCompatibility(this.configuredProviderInfo);
+  }
+  clearGlobalIndexUnlocked(projectRoot = this.projectRoot, roots = this.getScopedRoots(), recoveryDecision) {
+    const { store, invertedIndex, database } = this.requireLoadedIndexState();
+    store.load();
+    invertedIndex.load();
+    this.loadFileHashCache();
+    const compatibility = this.checkCompatibility();
+    const compatibilityDecision = recoveryDecision ?? (compatibility.compatible ? "compatible" : compatibility.code === "EMBEDDING_STRATEGY_MISMATCH" /* EMBEDDING_STRATEGY_MISMATCH */ ? "embedding-strategy-mismatch" : "incompatible");
+    const allMetadata = store.getAllMetadata();
+    const hasForeignData = allMetadata.some(({ metadata }) => !this.isFileInCurrentScope(metadata.filePath, roots)) || this.hasForeignScopedBranchData(projectRoot, roots) || this.hasForeignScopedFileHashData(roots) || this.hasForeignScopedFailedBatches(roots);
+    if (compatibilityDecision !== "compatible" && hasForeignData) {
+      if (compatibilityDecision === "embedding-strategy-mismatch") {
+        this.clearSharedIndexProjectData(store, invertedIndex, database, roots, projectRoot);
+        this.clearScopedFileHashCache(roots);
+        this.clearScopedFailedBatches(roots);
+        const projectIdentityHash = this.getProjectIdentityHash(projectRoot);
+        database.setMetadata(this.getProjectForceReembedMetadataKey(projectIdentityHash), "true");
+        database.deleteMetadata(this.getProjectEmbeddingStrategyMetadataKey(projectIdentityHash));
+        database.deleteMetadata(this.getProjectMigrationFinalizedMetadataKey(projectIdentityHash));
+        if (projectRoot === this.projectRoot) {
           this.indexCompatibility = { compatible: true };
-          return;
         }
-        throw new Error(
-          `Global index compatibility reset is unsafe because the shared index contains files from other projects. The current global index cannot be force-rebuilt for ${this.projectRoot} without deleting other repositories' indexed data. Use scope="project" for isolated rebuilds, or manually delete the shared global index if you intend to rebuild all projects.`
-        );
-      }
-      if (!hasForeignData) {
-        const clearedBranchKeys2 = database.getAllBranches();
-        store.clear();
-        store.save();
-        invertedIndex.clear();
-        this.saveInvertedIndex(invertedIndex);
-        this.fileHashCache.clear();
-        this.saveFileHashCache();
-        database.clearAllIndexedData();
-        this.deleteBranchCommitMetadata(database, clearedBranchKeys2);
-        this.clearFailedBatchState();
-        database.deleteMetadata("index.version");
-        database.deleteMetadata("index.pathStorageVersion");
-        database.deleteMetadata("index.embeddingProvider");
-        database.deleteMetadata("index.embeddingModel");
-        database.deleteMetadata("index.embeddingDimensions");
-        database.deleteMetadata("index.embeddingStrategyVersion");
-        database.deleteMetadata(this.getProjectEmbeddingStrategyMetadataKey());
-        database.deleteMetadata(this.getProjectForceReembedMetadataKey());
-        database.deleteMetadata(this.getLegacyMigrationMetadataKey());
-        database.deleteMetadata("index.createdAt");
-        database.deleteMetadata("index.updatedAt");
-        this.indexCompatibility = this.validateIndexCompatibility(this.configuredProviderInfo);
         return;
       }
-      this.clearSharedIndexProjectData(store, invertedIndex, database, roots);
-      this.clearScopedFileHashCache(roots);
-      this.clearScopedFailedBatches(roots);
+      throw new Error(
+        `Global index compatibility reset is unsafe because the shared index contains files from other projects. The current global index cannot be force-rebuilt for ${projectRoot} without deleting other repositories' indexed data. Use scope="project" for isolated rebuilds, or manually delete the shared global index if you intend to rebuild all projects.`
+      );
+    }
+    if (!hasForeignData) {
+      this.clearGlobalIndexDataUnlocked(projectRoot);
+      return;
+    }
+    this.clearSharedIndexProjectData(store, invertedIndex, database, roots, projectRoot);
+    this.clearScopedFileHashCache(roots);
+    this.clearScopedFailedBatches(roots);
+    if (projectRoot === this.projectRoot) {
       this.indexCompatibility = compatibility;
+    }
+  }
+  async clearIndexUnlocked(recoveryDecision) {
+    const { store, invertedIndex, database } = this.requireLoadedIndexState();
+    if (this.config.scope === "global") {
+      this.clearGlobalIndexUnlocked(this.projectRoot, this.getScopedRoots(), recoveryDecision);
       return;
     }
     if (!this.isProjectOwnedIndexPath()) {
@@ -11915,6 +12505,7 @@ var Indexer = class _Indexer {
       )) {
         const chunks = retryBatch.map(({ chunk }) => chunk);
         const attemptCounts = new Map(retryBatch.map(({ chunk, attemptCount }) => [chunk.id, attemptCount]));
+        this.restoreMissingChunkRows(database, chunks);
         const batchResult = await this.processPendingChunkBatch(chunks, {
           store,
           provider,
@@ -11929,6 +12520,7 @@ var Indexer = class _Indexer {
           forceReembed: false,
           reuseCachedEmbeddings: false,
           incrementRepeatedFailures: false,
+          forceSingleItemBatches: true,
           onSucceeded: (succeededChunks) => {
             database.addChunksToBranchBatch(
               this.getBranchCatalogKey(),
@@ -11950,9 +12542,12 @@ var Indexer = class _Indexer {
       this.saveInvertedIndex(invertedIndex);
     }
     if (roots && succeeded > 0 && remaining === 0 && this.hasProjectForceReembedPending()) {
-      database.deleteMetadata(this.getProjectForceReembedMetadataKey());
-      this.saveIndexMetadata(configuredProviderInfo);
-      this.indexCompatibility = { compatible: true };
+      const migrationFinalized = database.getMetadata(this.getProjectMigrationFinalizedMetadataKey()) === "true";
+      if (migrationFinalized) {
+        database.deleteMetadata(this.getProjectForceReembedMetadataKey());
+        this.saveIndexMetadata(configuredProviderInfo);
+        this.indexCompatibility = { compatible: true };
+      }
     }
     return { succeeded, failed, remaining };
   }
@@ -11974,7 +12569,8 @@ var Indexer = class _Indexer {
           latestById.set(chunkId, {
             attemptCount: batch.attemptCount,
             error: batch.error,
-            lastAttempt: batch.lastAttempt
+            lastAttempt: batch.lastAttempt,
+            chunks: [rawChunk]
           });
         }
       }
@@ -12041,6 +12637,7 @@ var Indexer = class _Indexer {
         this.getBranchCatalogKeys().flatMap((branchKey) => database.getBranchChunkIds(branchKey))
       );
     }
+    const temporalChunkIds = this.getTemporalChunkIds(database, options);
     const { hasInitializedBranchCatalog, shouldPrefilterByBranch } = this.getBranchPrefilterState(database, branchChunkIds);
     const prefilterMs = import_perf_hooks.performance.now() - prefilterStartTime;
     const vectorStartTime = import_perf_hooks.performance.now();
@@ -12049,7 +12646,8 @@ var Indexer = class _Indexer {
       embedding,
       limit * 2,
       branchChunkIds,
-      shouldPrefilterByBranch
+      shouldPrefilterByBranch,
+      temporalChunkIds
     );
     const vectorMs = import_perf_hooks.performance.now() - vectorStartTime;
     if (this.config.scope !== "global" && branchChunkIds && !hasInitializedBranchCatalog) {
@@ -12631,6 +13229,36 @@ function resolveConfigPathValue(value, baseDir) {
   const absolutePath = path16.isAbsolute(trimmed) ? trimmed : path16.resolve(baseDir, trimmed);
   return path16.normalize(absolutePath);
 }
+function serializeConfigPathValue(value, baseDir) {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+  if (!path16.isAbsolute(trimmed)) {
+    return normalizePathSeparators(path16.normalize(trimmed));
+  }
+  const relativePath = path16.relative(baseDir, trimmed);
+  if (!relativePath || !relativePath.startsWith("..") && !path16.isAbsolute(relativePath)) {
+    return normalizePathSeparators(path16.normalize(relativePath || "."));
+  }
+  return path16.normalize(trimmed);
+}
+function resolveKnowledgeBasePath(value, projectRoot) {
+  return path16.isAbsolute(value) ? value : path16.resolve(projectRoot, value);
+}
+function normalizeKnowledgeBasePath(value, projectRoot) {
+  return path16.normalize(resolveKnowledgeBasePath(value, projectRoot));
+}
+function hasMatchingKnowledgeBasePath(knowledgeBases, inputPath, projectRoot) {
+  const normalizedInput = path16.normalize(inputPath);
+  return knowledgeBases.some((kb) => normalizeKnowledgeBasePath(kb, projectRoot) === normalizedInput);
+}
+function findKnowledgeBasePathIndex(knowledgeBases, inputPath, projectRoot) {
+  const normalizedInput = path16.normalize(inputPath);
+  return knowledgeBases.findIndex(
+    (kb) => path16.normalize(kb) === normalizedInput || normalizeKnowledgeBasePath(kb, projectRoot) === normalizedInput
+  );
+}
 
 // src/tools/format-communities.ts
 function compareText(left, right) {
@@ -14337,7 +14965,7 @@ function applyProjectOverride(merged, normalizedProjectConfig, globalConfig, key
 function mergeUniqueStringArray(values) {
   return [...new Set(values.map((value) => String(value).trim()))];
 }
-function normalizeKnowledgeBasePath(value) {
+function normalizeKnowledgeBasePath2(value) {
   let normalized = path19.normalize(String(value).trim());
   const root = path19.parse(normalized).root;
   while (normalized.length > root.length && /[\\/]$/.test(normalized)) {
@@ -14346,7 +14974,7 @@ function normalizeKnowledgeBasePath(value) {
   return normalized;
 }
 function mergeKnowledgeBasePaths(values) {
-  return [...new Set(values.map((value) => normalizeKnowledgeBasePath(value)).filter((value) => value.length > 0))];
+  return [...new Set(values.map((value) => normalizeKnowledgeBasePath2(value)).filter((value) => value.length > 0))];
 }
 function validateConfigLayerShape(rawConfig, filePath) {
   if (!isRecord(rawConfig)) {
@@ -14476,9 +15104,30 @@ function toConfigRecord(rawConfig) {
   }
   return { ...rawConfig };
 }
+function getConfigPath(projectRoot, host) {
+  return resolveWritableProjectConfigPath(projectRoot, host);
+}
 function loadRuntimeConfig(projectRoot, host) {
   return normalizeKnowledgeBasePaths(toConfigRecord(loadMergedConfig(projectRoot, host)), projectRoot);
 }
+function loadEditableConfig(projectRoot, host) {
+  return normalizeKnowledgeBasePaths(toConfigRecord(loadProjectConfigLayer(projectRoot, host)), projectRoot);
+}
+function saveConfig(projectRoot, config, host) {
+  const configPath = getConfigPath(projectRoot, host);
+  const configDir = path20.dirname(configPath);
+  const configBaseDir = path20.dirname(configDir);
+  if (!(0, import_fs13.existsSync)(configDir)) {
+    (0, import_fs13.mkdirSync)(configDir, { recursive: true });
+  }
+  const serializableConfig = { ...config };
+  if (Array.isArray(serializableConfig.knowledgeBases)) {
+    serializableConfig.knowledgeBases = serializableConfig.knowledgeBases.map(
+      (kb) => serializeConfigPathValue(kb, configBaseDir)
+    );
+  }
+  (0, import_fs13.writeFileSync)(configPath, JSON.stringify(serializableConfig, null, 2) + "\n", "utf-8");
+}
 
 // src/tools/operation-runtime.ts
 var indexerCache = /* @__PURE__ */ new Map();
@@ -14697,9 +15346,11 @@ async function searchCodebase(projectRoot, host, query, options = {}) {
     contextLines: options.contextLines,
     metadataOnly: options.metadataOnly,
     definitionIntent: options.definitionIntent,
+    prioritizeSourcePaths: options.prioritizeSourcePaths,
     blameAuthor: options.blameAuthor,
     blameSha: options.blameSha,
     blameSince: options.blameSince,
+    blameUntil: options.blameUntil,
     trace: options.trace
   });
 }
@@ -14745,7 +15396,9 @@ async function findSimilarCode(projectRoot, host, code, options = {}) {
     fileType: options.fileType,
     directory: options.directory,
     chunkType: options.chunkType,
-    excludeFile: options.excludeFile
+    excludeFile: options.excludeFile,
+    blameSince: options.blameSince,
+    blameUntil: options.blameUntil
   });
 }
 async function implementationLookup(projectRoot, host, query, options = {}) {
@@ -14808,6 +15461,9 @@ async function runIndexCodebase(projectRoot, host, args, onProgress) {
     if (args.estimateOnly) {
       return { kind: "estimate", estimate: await indexer.estimateCost() };
     }
+    if (args.dryRun) {
+      return { kind: "dryrun", dryrun: await indexer.dryRunCost() };
+    }
     const coordinated = runCoordinatedIndex(root, host, args.force ?? false, (progress) => {
       if (onProgress) {
         void onProgress(formatProgressTitle(progress), {
@@ -14991,6 +15647,141 @@ async function getIndexLogs(projectRoot, host, args) {
   }).join("\n");
   return { kind: "entries", text };
 }
+function addKnowledgeBase(projectRoot, host, knowledgeBasePath) {
+  const root = getProjectRoot(projectRoot, host);
+  const inputPath = knowledgeBasePath.trim();
+  const normalizedPath3 = path21.resolve(
+    path21.isAbsolute(inputPath) ? inputPath : resolveKnowledgeBasePath(inputPath, root)
+  );
+  if (!(0, import_fs14.existsSync)(normalizedPath3)) {
+    return `Error: Directory does not exist: ${normalizedPath3}`;
+  }
+  let realPath;
+  try {
+    realPath = (0, import_fs14.realpathSync)(normalizedPath3);
+  } catch {
+    return `Error: Cannot resolve path: ${normalizedPath3}`;
+  }
+  const blockedPrefixes = [
+    "/etc",
+    "/proc",
+    "/sys",
+    "/dev",
+    "/boot",
+    "/root",
+    "/var/run",
+    "/var/log"
+  ];
+  const homeDir = process.platform === "win32" ? process.env.USERPROFILE ?? "" : process.env.HOME ?? "";
+  const sensitiveDotDirs = [
+    ".ssh",
+    ".gnupg",
+    ".aws",
+    ".config/gcloud",
+    ".docker",
+    ".kube"
+  ];
+  for (const prefix of blockedPrefixes) {
+    if (realPath === prefix || realPath.startsWith(`${prefix}/`)) {
+      return `Error: Adding sensitive directory as knowledge base is not allowed: ${normalizedPath3}`;
+    }
+  }
+  for (const dotDir of sensitiveDotDirs) {
+    const sensitiveDir = path21.join(homeDir, dotDir);
+    if (sensitiveDir && (realPath === sensitiveDir || realPath.startsWith(`${sensitiveDir}/`))) {
+      return `Error: Adding sensitive directory as knowledge base is not allowed: ${normalizedPath3}`;
+    }
+  }
+  try {
+    const stat5 = (0, import_fs14.statSync)(normalizedPath3);
+    if (!stat5.isDirectory()) {
+      return `Error: Path is not a directory: ${normalizedPath3}`;
+    }
+  } catch (error) {
+    return `Error: Cannot access directory: ${normalizedPath3} - ${error instanceof Error ? error.message : String(error)}`;
+  }
+  const config = loadEditableConfig(root, host);
+  const knowledgeBases = Array.isArray(config.knowledgeBases) ? config.knowledgeBases : [];
+  const alreadyExists = hasMatchingKnowledgeBasePath(knowledgeBases, normalizedPath3, root);
+  if (alreadyExists) {
+    return `Knowledge base already configured: ${normalizedPath3}`;
+  }
+  knowledgeBases.push(normalizedPath3);
+  config.knowledgeBases = knowledgeBases;
+  saveConfig(root, config, host);
+  refreshIndexerForDirectory(root, host);
+  let result = `${normalizedPath3}
+`;
+  result += `Total knowledge bases: ${knowledgeBases.length}
+`;
+  result += `Config path: ${getConfigPath(root, host)}
+`;
+  result += `
+Run /index to rebuild the index with the new knowledge base.`;
+  return result;
+}
+function listKnowledgeBases(projectRoot, host) {
+  const root = getProjectRoot(projectRoot, host);
+  const config = loadRuntimeConfig(root, host);
+  const knowledgeBases = Array.isArray(config.knowledgeBases) ? config.knowledgeBases : [];
+  if (knowledgeBases.length === 0) {
+    return "No knowledge bases configured. Use add_knowledge_base to add folders.";
+  }
+  let result = `Knowledge Bases (${knowledgeBases.length}):
+
+`;
+  for (let i = 0; i < knowledgeBases.length; i++) {
+    const kb = knowledgeBases[i];
+    const resolvedPath = resolveKnowledgeBasePath(kb, root);
+    const exists = (0, import_fs14.existsSync)(resolvedPath);
+    result += `[${i + 1}] ${kb}
+`;
+    result += `    Resolved: ${resolvedPath}
+`;
+    result += `    Status: ${exists ? "Exists" : "NOT FOUND"}
+`;
+    if (exists) {
+      try {
+        const stat5 = (0, import_fs14.statSync)(resolvedPath);
+        result += `    Type: ${stat5.isDirectory() ? "Directory" : "File"}
+`;
+      } catch {
+      }
+    }
+    result += "\n";
+  }
+  const hasHostConfig = (0, import_fs14.existsSync)(path21.join(root, getHostProjectConfigRelativePath(host)));
+  if (hasHostConfig) {
+    result += `
+Config sources: 1 file(s).`;
+  }
+  result += `
+Config file: ${getConfigPath(root, host)}`;
+  return result;
+}
+function removeKnowledgeBase(projectRoot, host, knowledgeBasePath) {
+  const root = getProjectRoot(projectRoot, host);
+  const config = loadEditableConfig(root, host);
+  const knowledgeBases = Array.isArray(config.knowledgeBases) ? config.knowledgeBases : [];
+  const index = findKnowledgeBasePathIndex(knowledgeBases, knowledgeBasePath, root);
+  if (index === -1) {
+    return `Knowledge base not found: ${knowledgeBasePath}`;
+  }
+  const removed = knowledgeBases.splice(index, 1)[0];
+  config.knowledgeBases = knowledgeBases;
+  saveConfig(root, config, host);
+  refreshIndexerForDirectory(root, host);
+  let result = `Removed: ${removed}
+
+`;
+  result += `Remaining knowledge bases: ${knowledgeBases.length}
+`;
+  result += `Config saved to: ${getConfigPath(root, host)}
+`;
+  result += `
+Run /index to rebuild the index without the removed knowledge base.`;
+  return result;
+}
 
 // src/tools/context-search.ts
 var MIN_CONTEXT_RESULT_LIMIT = 1;
@@ -15219,13 +16010,19 @@ async function resolveSearchContext(input, operations) {
       (trace) => operations.lookup(symbol, MAX_CONTEXT_RESULT_LIMIT, scope, input.diagnostic ? trace : void 0)
     );
   };
-  const tryConceptualSearch = async (searchQuery, scope, relaxedFieldsForAttempt) => {
+  const tryConceptualSearch = async (searchQuery, scope, relaxedFieldsForAttempt, prioritizeSourcePaths) => {
     return recordAttempt(
       "conceptual",
       searchQuery,
       scope,
       relaxedFieldsForAttempt,
-      (trace) => operations.search(searchQuery, MAX_CONTEXT_RESULT_LIMIT, scope, input.diagnostic ? trace : void 0)
+      (trace) => operations.search(
+        searchQuery,
+        MAX_CONTEXT_RESULT_LIMIT,
+        scope,
+        input.diagnostic ? trace : void 0,
+        { prioritizeSourcePaths }
+      )
     );
   };
   const findSuccessfulAttemptState = (route) => {
@@ -15353,10 +16150,12 @@ Explicit symbol lookup only; conceptual search was not attempted.`
     }
   }
   for (const attempt of conceptualAttemptPlan) {
+    const attemptIntent = analyzeQueryIntent(attempt.queryText);
+    const prioritizeSourcePaths = attemptIntent.primary !== "docs" && attemptIntent.primary !== "test";
     if (inferredSymbol && attempt.queryText === inferredSymbol && attempt.queryText !== query) {
       decisions.fallbackFromOriginalConceptualToInferred = true;
     }
-    const results = await tryConceptualSearch(attempt.queryText, attempt.scope, attempt.relaxed);
+    const results = await tryConceptualSearch(attempt.queryText, attempt.scope, attempt.relaxed, prioritizeSourcePaths);
     if (results.length > 0) {
       const heading = buildPackHeading("conceptual", decisions);
       const intent = analyzeQueryIntent(attempt.queryText);
@@ -15493,12 +16292,13 @@ async function resolveCodebaseContextUnmeasured(projectRoot, host, input) {
       directory: scope.directory,
       trace
     }),
-    search: (queryText, retrievalLimit, scope, trace) => searchCodebase(projectRoot, host, queryText, {
+    search: (queryText, retrievalLimit, scope, trace, searchOptions) => searchCodebase(projectRoot, host, queryText, {
       limit: retrievalLimit,
       fileType: scope.fileType,
       directory: scope.directory,
       metadataOnly: true,
-      trace
+      trace,
+      prioritizeSourcePaths: searchOptions?.prioritizeSourcePaths
     })
   });
 }
@@ -16999,12 +17799,13 @@ async function runEvaluation(options) {
           fileType: scope.fileType,
           directory: scope.directory
         }),
-        search: (searchQuery, limit, scope) => indexer.search(searchQuery, limit, {
+        search: (searchQuery, limit, scope, _trace, searchOptions) => indexer.search(searchQuery, limit, {
           metadataOnly: true,
           filterByBranch: !!query.expected.branch,
           definitionIntent: false,
           fileType: scope.fileType,
-          directory: scope.directory
+          directory: scope.directory,
+          prioritizeSourcePaths: searchOptions?.prioritizeSourcePaths
         })
       }) : void 0;
       const result = editContextResult?.results ?? contextResult?.details?.results ?? await indexer.search(query.query, 10, {
@@ -17590,6 +18391,7 @@ async function executeCodebaseEditContext(projectRoot, host, args) {
 async function executeIndexCodebase(projectRoot, host, args, onProgress) {
   const result = await runIndexCodebase(projectRoot, host, args, onProgress);
   if (result.kind === "estimate") return { text: formatCostEstimate(result.estimate) };
+  if (result.kind === "dryrun") return { text: formatDryRunEstimate(result.dryrun) };
   if (result.kind === "busy") return { text: result.text, isError: true };
   if (result.kind === "message") return { text: result.text };
   return { text: formatIndexStats(result.stats, args.verbose ?? false) };
@@ -17781,11 +18583,21 @@ var PI_TOOL_NAMES = [
   TOOL_NAME.PI_KNOWLEDGE_BASE_ADD,
   TOOL_NAME.PI_KNOWLEDGE_BASE_REMOVE
 ];
+var MCP_TOOL_NAMES = [
+  ...PORTABLE_TOOL_NAMES,
+  TOOL_NAME.ADD_KNOWLEDGE_BASE,
+  TOOL_NAME.LIST_KNOWLEDGE_BASES,
+  TOOL_NAME.REMOVE_KNOWLEDGE_BASE
+];
 
 // src/adapters/mcp/register-tools.ts
 function allowNullAsUndefined(schema) {
   return import_zod2.z.preprocess((value) => value === null ? void 0 : value, schema);
 }
+function knowledgeBaseResult(text) {
+  const content = [{ type: "text", text }];
+  return text.startsWith("Error: ") ? { content, isError: true } : { content };
+}
 function registerMcpTools(server, runtime) {
   server.tool(
     TOOL_NAME.CODEBASE_CONTEXT,
@@ -17846,7 +18658,8 @@ function registerMcpTools(server, runtime) {
       contextLines: allowNullAsUndefined(import_zod2.z.number().optional()).describe("Number of extra lines to include before/after each match (default: 0)"),
       blameAuthor: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by git blame author name or email"),
       blameSha: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by git blame commit SHA or prefix"),
-      blameSince: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or after this date")
+      blameSince: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or after this date"),
+      blameUntil: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or before this date")
     },
     async (args) => {
       return searchCodebaseWithEffectiveness(runtime.projectRoot, runtime.host, "search", args.query, {
@@ -17857,7 +18670,8 @@ function registerMcpTools(server, runtime) {
         contextLines: args.contextLines,
         blameAuthor: args.blameAuthor,
         blameSha: args.blameSha,
-        blameSince: args.blameSince
+        blameSince: args.blameSince,
+        blameUntil: args.blameUntil
       }, (results) => {
         const text = results.length === 0 ? "No matching code found. Try a different query or run index_codebase first." : `Found ${results.length} results for "${args.query}":
 
@@ -17877,7 +18691,8 @@ ${formatSearchResults(results, "score")}`;
       chunkType: allowNullAsUndefined(import_zod2.z.enum(CHUNK_TYPES).optional()).describe("Filter by code chunk type"),
       blameAuthor: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by git blame author name or email"),
       blameSha: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by git blame commit SHA or prefix"),
-      blameSince: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or after this date")
+      blameSince: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or after this date"),
+      blameUntil: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or before this date")
     },
     async (args) => {
       return searchCodebaseWithEffectiveness(runtime.projectRoot, runtime.host, "peek", args.query, {
@@ -17888,7 +18703,8 @@ ${formatSearchResults(results, "score")}`;
         metadataOnly: true,
         blameAuthor: args.blameAuthor,
         blameSha: args.blameSha,
-        blameSince: args.blameSince
+        blameSince: args.blameSince,
+        blameUntil: args.blameUntil
       }, (results) => {
         const text = results.length === 0 ? "No matching code found. Try a different query or run index_codebase first." : `Found ${results.length} locations for "${args.query}":
 
@@ -17903,6 +18719,7 @@ ${formatCodebasePeek(results)}`;
     {
       force: allowNullAsUndefined(import_zod2.z.boolean().optional().default(false)).describe("Force reindex even if already indexed"),
       estimateOnly: allowNullAsUndefined(import_zod2.z.boolean().optional().default(false)).describe("Only show cost estimate without indexing"),
+      dryRun: allowNullAsUndefined(import_zod2.z.boolean().optional().default(false)).describe("Parse the file set and report the exact embedding token total without indexing. Read-only; the index is not changed. The total is the value 'Tokens used' climbs to for a force index (and an upper bound for an incremental)."),
       verbose: allowNullAsUndefined(import_zod2.z.boolean().optional().default(false)).describe("Show detailed info about skipped files and parsing failures")
     },
     async (args) => {
@@ -17965,7 +18782,9 @@ ${formatCodebasePeek(results)}`;
       fileType: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
       directory: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
       chunkType: allowNullAsUndefined(import_zod2.z.enum(CHUNK_TYPES).optional()).describe("Filter by code chunk type"),
-      excludeFile: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Exclude results from this file path")
+      excludeFile: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Exclude results from this file path"),
+      blameSince: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or after this date"),
+      blameUntil: allowNullAsUndefined(import_zod2.z.string().optional()).describe("Filter to chunks last changed on or before this date")
     },
     async (args) => {
       const results = await findSimilarCode(runtime.projectRoot, runtime.host, args.code, {
@@ -17973,7 +18792,9 @@ ${formatCodebasePeek(results)}`;
         fileType: args.fileType,
         directory: args.directory,
         chunkType: args.chunkType,
-        excludeFile: args.excludeFile
+        excludeFile: args.excludeFile,
+        blameSince: args.blameSince,
+        blameUntil: args.blameUntil
       });
       if (results.length === 0) {
         return { content: [{ type: "text", text: "No similar code found. Try a different snippet or run index_codebase first." }] };
@@ -18077,12 +18898,43 @@ ${formatSearchResults(results)}` }] };
       return { content: [{ type: "text", text: result.text }] };
     }
   );
+  server.tool(
+    TOOL_NAME.ADD_KNOWLEDGE_BASE,
+    "Add a folder as a knowledge base to the semantic search index. The folder is indexed alongside the project code on the next index run. Provide an absolute path or a path relative to the project root. The path is written to the project-local host config of this MCP server (under the server project root), not to a user-global config, and the index is refreshed. Git blame metadata is collected only for files in the project git repo; knowledge-base files outside the repo remain searchable by content but have no blame. A knowledge base that appears in list_knowledge_bases but was inherited from a global config cannot be removed by this tool.",
+    {
+      path: import_zod2.z.string().describe("Path to the folder to add as a knowledge base (absolute or relative to the project root)")
+    },
+    async (args) => {
+      const result = addKnowledgeBase(runtime.projectRoot, runtime.host, args.path);
+      return knowledgeBaseResult(result);
+    }
+  );
+  server.tool(
+    TOOL_NAME.LIST_KNOWLEDGE_BASES,
+    "List the configured knowledge base folders that the index includes alongside the project code. The list is the union of project-local and user-global knowledge bases; each entry shows the resolved path and whether it exists.",
+    {},
+    async () => {
+      const result = listKnowledgeBases(runtime.projectRoot, runtime.host);
+      return knowledgeBaseResult(result);
+    }
+  );
+  server.tool(
+    TOOL_NAME.REMOVE_KNOWLEDGE_BASE,
+    "Remove a knowledge base folder from the semantic search index and refresh the index. The path must match a project-local configured path exactly. Knowledge bases inherited from a user-global config are not removable by this tool.",
+    {
+      path: import_zod2.z.string().describe("Path of the knowledge base to remove (must match a project-local configured path exactly)")
+    },
+    async (args) => {
+      const result = removeKnowledgeBase(runtime.projectRoot, runtime.host, args.path.trim());
+      return knowledgeBaseResult(result);
+    }
+  );
 }
 
 // src/adapters/mcp/server.ts
 function getServerInstructions(host) {
   const hostText = `host ${host}`;
-  return `This MCP server is the preferred codebase-understanding path for ${hostText}. Start a repository task with index_status when index readiness or freshness is unknown. Use codebase_context as the preferred first entry point because it returns a token-budgeted location pack and routes to definitions or call-graph helpers when symbol intent is present. Keep the default tokenBudget for normal discovery, then use implementation_lookup, codebase_search, or a targeted file read only for selected locations that need source content. Use codebase_peek for direct conceptual location lookup. For exact identifiers or exhaustive matches, use grep. After identifying symbols, use call_graph or call_graph_path to trace dependencies. If the index is unavailable, run index_codebase, then retry the retrieval tool.`;
+  return `This MCP server is the preferred codebase-understanding path for ${hostText}. Start a repository task with index_status when index readiness or freshness is unknown. Use codebase_context as the preferred first entry point because it returns a token-budgeted location pack and routes to definitions or call-graph helpers when symbol intent is present. For code changes with a known or suspected symbol target, optionally call codebase_edit_context as a compact pre-edit step for bounded source plus direct callers and callees before broad file reads. Keep the default tokenBudget for normal discovery, then use implementation_lookup, codebase_search, or a targeted file read only for selected locations that need source content. Use codebase_peek for direct conceptual location lookup. For exact identifiers or exhaustive matches, use grep. After identifying symbols, use call_graph or call_graph_path to trace dependencies. If the index is unavailable, run index_codebase, then retry the retrieval tool.`;
 }
 function createMcpServer(projectRoot, config, host) {
   const server = new import_mcp.McpServer({
@@ -21500,6 +22352,7 @@ function parseIndexArgs(argv, cwd) {
   let config;
   let force = false;
   let estimateOnly = false;
+  let dryRun = false;
   let verbose = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -21537,13 +22390,16 @@ function parseIndexArgs(argv, cwd) {
       host = parseHostMode(value);
       continue;
     }
-    if (arg === "--force" || arg === "--estimate-only" || arg === "--verbose") {
+    if (arg === "--force" || arg === "--estimate-only" || arg === "--dry-run" || arg === "--verbose") {
       if (arg === "--force") {
         force = true;
       }
       if (arg === "--estimate-only") {
         estimateOnly = true;
       }
+      if (arg === "--dry-run") {
+        dryRun = true;
+      }
       if (arg === "--verbose") {
         verbose = true;
       }
@@ -21554,7 +22410,7 @@ function parseIndexArgs(argv, cwd) {
     }
     throw new Error(`Unknown index option: ${arg}`);
   }
-  return { project, host, config, force, estimateOnly, verbose };
+  return { project, host, config, force, estimateOnly, dryRun, verbose };
 }
 function loadCliRawConfig(args) {
   return args.config ? loadConfigFile(args.config) : loadMergedConfig(args.project, args.host);
@@ -21571,6 +22427,7 @@ Options:
   --config <path>        Explicit JSON config path
   --force                Rebuild index even if already up to date
   --estimate-only        Estimate indexing cost only
+  --dry-run              Parse only; report the exact embedding token total without indexing
   --verbose              Include detailed final index statistics
   --help                 Show this message
 
@@ -21766,6 +22623,7 @@ async function handleIndexCommand(argv, cwd, deps = {}) {
     const indexArgs = {
       force: parsedArgs.force,
       estimateOnly: parsedArgs.estimateOnly,
+      dryRun: parsedArgs.dryRun,
       verbose: parsedArgs.verbose
     };
     const result = await runIndex(parsedArgs.project, parsedArgs.host, indexArgs, (title, metadata) => {