opencode-codebase-index 0.14.0 → 0.16.0

package/dist/cli.js

@@ -491,7 +491,7 @@ var require_ignore = __commonJS({
       //   path matching.
       // - check `string` either `MODE_IGNORE` or `MODE_CHECK_IGNORE`
       // @returns {TestResult} true if a file is ignored
-      test(path26, checkUnignored, mode) {
+      test(path27, checkUnignored, mode) {
         let ignored = false;
         let unignored = false;
         let matchedRule;
@@ -500,7 +500,7 @@ var require_ignore = __commonJS({
           if (unignored === negative && ignored !== unignored || negative && !ignored && !unignored && !checkUnignored) {
             return;
           }
-          const matched = rule[mode].test(path26);
+          const matched = rule[mode].test(path27);
           if (!matched) {
             return;
           }
@@ -521,17 +521,17 @@ var require_ignore = __commonJS({
     var throwError = (message, Ctor) => {
       throw new Ctor(message);
     };
-    var checkPath = (path26, originalPath, doThrow) => {
-      if (!isString(path26)) {
+    var checkPath = (path27, originalPath, doThrow) => {
+      if (!isString(path27)) {
         return doThrow(
           `path must be a string, but got \`${originalPath}\``,
           TypeError
         );
       }
-      if (!path26) {
+      if (!path27) {
         return doThrow(`path must not be empty`, TypeError);
       }
-      if (checkPath.isNotRelative(path26)) {
+      if (checkPath.isNotRelative(path27)) {
         const r = "`path.relative()`d";
         return doThrow(
           `path should be a ${r} string, but got "${originalPath}"`,
@@ -540,7 +540,7 @@ var require_ignore = __commonJS({
       }
       return true;
     };
-    var isNotRelative = (path26) => REGEX_TEST_INVALID_PATH.test(path26);
+    var isNotRelative = (path27) => REGEX_TEST_INVALID_PATH.test(path27);
     checkPath.isNotRelative = isNotRelative;
     checkPath.convert = (p) => p;
     var Ignore2 = class {
@@ -570,19 +570,19 @@ var require_ignore = __commonJS({
       }
       // @returns {TestResult}
       _test(originalPath, cache, checkUnignored, slices) {
-        const path26 = originalPath && checkPath.convert(originalPath);
+        const path27 = originalPath && checkPath.convert(originalPath);
         checkPath(
-          path26,
+          path27,
           originalPath,
           this._strictPathCheck ? throwError : RETURN_FALSE
         );
-        return this._t(path26, cache, checkUnignored, slices);
+        return this._t(path27, cache, checkUnignored, slices);
       }
-      checkIgnore(path26) {
-        if (!REGEX_TEST_TRAILING_SLASH.test(path26)) {
-          return this.test(path26);
+      checkIgnore(path27) {
+        if (!REGEX_TEST_TRAILING_SLASH.test(path27)) {
+          return this.test(path27);
         }
-        const slices = path26.split(SLASH2).filter(Boolean);
+        const slices = path27.split(SLASH2).filter(Boolean);
         slices.pop();
         if (slices.length) {
           const parent = this._t(
@@ -595,18 +595,18 @@ var require_ignore = __commonJS({
             return parent;
           }
         }
-        return this._rules.test(path26, false, MODE_CHECK_IGNORE);
+        return this._rules.test(path27, false, MODE_CHECK_IGNORE);
       }
-      _t(path26, cache, checkUnignored, slices) {
-        if (path26 in cache) {
-          return cache[path26];
+      _t(path27, cache, checkUnignored, slices) {
+        if (path27 in cache) {
+          return cache[path27];
         }
         if (!slices) {
-          slices = path26.split(SLASH2).filter(Boolean);
+          slices = path27.split(SLASH2).filter(Boolean);
         }
         slices.pop();
         if (!slices.length) {
-          return cache[path26] = this._rules.test(path26, checkUnignored, MODE_IGNORE);
+          return cache[path27] = this._rules.test(path27, checkUnignored, MODE_IGNORE);
         }
         const parent = this._t(
           slices.join(SLASH2) + SLASH2,
@@ -614,29 +614,29 @@ var require_ignore = __commonJS({
           checkUnignored,
           slices
         );
-        return cache[path26] = parent.ignored ? parent : this._rules.test(path26, checkUnignored, MODE_IGNORE);
+        return cache[path27] = parent.ignored ? parent : this._rules.test(path27, checkUnignored, MODE_IGNORE);
       }
-      ignores(path26) {
-        return this._test(path26, this._ignoreCache, false).ignored;
+      ignores(path27) {
+        return this._test(path27, this._ignoreCache, false).ignored;
       }
       createFilter() {
-        return (path26) => !this.ignores(path26);
+        return (path27) => !this.ignores(path27);
       }
       filter(paths) {
         return makeArray(paths).filter(this.createFilter());
       }
       // @returns {TestResult}
-      test(path26) {
-        return this._test(path26, this._testCache, true);
+      test(path27) {
+        return this._test(path27, this._testCache, true);
       }
     };
     var factory = (options) => new Ignore2(options);
-    var isPathValid = (path26) => checkPath(path26 && checkPath.convert(path26), path26, RETURN_FALSE);
+    var isPathValid = (path27) => checkPath(path27 && checkPath.convert(path27), path27, RETURN_FALSE);
     var setupWindows = () => {
       const makePosix = (str) => /^\\\\\?\\/.test(str) || /["<>|\u0000-\u001F]+/u.test(str) ? str : str.replace(/\\/g, "/");
       checkPath.convert = makePosix;
       const REGEX_TEST_WINDOWS_PATH_ABSOLUTE = /^[a-z]:\//i;
-      checkPath.isNotRelative = (path26) => REGEX_TEST_WINDOWS_PATH_ABSOLUTE.test(path26) || isNotRelative(path26);
+      checkPath.isNotRelative = (path27) => REGEX_TEST_WINDOWS_PATH_ABSOLUTE.test(path27) || isNotRelative(path27);
     };
     if (
       // Detect `process` so that it can run in browsers.
@@ -653,17 +653,17 @@ var require_ignore = __commonJS({
 
 // src/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { realpathSync as realpathSync2, writeFileSync as writeFileSync6 } from "fs";
-import * as os5 from "os";
-import * as path25 from "path";
+import { realpathSync as realpathSync3, writeFileSync as writeFileSync7 } from "fs";
+import * as os6 from "os";
+import * as path26 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/config/constants.ts
 var DEFAULT_INCLUDE = [
-  "**/*.{ts,tsx,js,jsx,mjs,cjs}",
+  "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
   "**/*.{py,pyi}",
-  "**/*.{go,rs,java,kt,scala}",
-  "**/*.{c,cpp,cc,h,hpp}",
+  "**/*.{go,rs,java,cs,kt,scala}",
+  "**/*.{c,cpp,cc,cxx,h,hpp,hxx}",
   "**/*.{rb,php,inc,swift}",
   "**/*.{cls,trigger}",
   "**/*.{vue,svelte,astro}",
@@ -1046,7 +1046,7 @@ var autoDetectProviders = AUTO_DETECT_PROVIDER_ORDER.filter(
 );
 
 // src/config/host.ts
-var HOST_MODES = ["opencode", "codex", "claude", "pi"];
+var HOST_MODES = ["opencode", "codex", "claude", "pi", "jcode"];
 function isSupportedHostMode(value) {
   return HOST_MODES.includes(value);
 }
@@ -1101,9 +1101,9 @@ import { mkdirSync, readFileSync, writeFileSync } from "fs";
 import * as path from "path";
 
 // src/eval/report-formatters.ts
-function assertFiniteNumber(value, path26) {
+function assertFiniteNumber(value, path27) {
   if (typeof value !== "number" || Number.isNaN(value) || !Number.isFinite(value)) {
-    throw new Error(`${path26} must be a finite number`);
+    throw new Error(`${path27} must be a finite number`);
   }
   return value;
 }
@@ -1291,13 +1291,13 @@ function buildPerQueryArtifact(perQuery) {
 }
 
 // src/eval/runner.ts
-import { existsSync as existsSync8 } from "fs";
-import * as path14 from "path";
+import { existsSync as existsSync9 } from "fs";
+import * as path15 from "path";
 import { performance as performance3 } from "perf_hooks";
 
 // src/indexer/index.ts
-import { existsSync as existsSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync2, renameSync, unlinkSync, mkdirSync as mkdirSync2, promises as fsPromises2 } from "fs";
-import * as path11 from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync7, statSync as statSync3, writeFileSync as writeFileSync3, renameSync as renameSync2, unlinkSync, mkdirSync as mkdirSync3, promises as fsPromises2 } from "fs";
+import * as path12 from "path";
 import { performance as performance2 } from "perf_hooks";
 import { execFile as execFile3 } from "child_process";
 import { promisify as promisify3 } from "util";
@@ -2579,17 +2579,17 @@ function validateExternalUrl(urlString) {
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     return { valid: false, reason: `Blocked protocol: ${parsed.protocol}` };
   }
-  const hostname = parsed.hostname.toLowerCase();
-  if (BLOCKED_HOSTNAMES.has(hostname)) {
-    return { valid: false, reason: `Blocked: cloud metadata service (${hostname})` };
+  const hostname2 = parsed.hostname.toLowerCase();
+  if (BLOCKED_HOSTNAMES.has(hostname2)) {
+    return { valid: false, reason: `Blocked: cloud metadata service (${hostname2})` };
   }
   for (const pattern of BLOCKED_METADATA_IPS) {
-    if (pattern.test(hostname)) {
-      return { valid: false, reason: `Blocked: cloud metadata IP (${hostname})` };
+    if (pattern.test(hostname2)) {
+      return { valid: false, reason: `Blocked: cloud metadata IP (${hostname2})` };
     }
   }
-  if (/^169\.254\./.test(hostname)) {
-    return { valid: false, reason: `Blocked: link-local address (${hostname})` };
+  if (/^169\.254\./.test(hostname2)) {
+    return { valid: false, reason: `Blocked: link-local address (${hostname2})` };
   }
   return { valid: true };
 }
@@ -3779,6 +3779,12 @@ function createMockNativeBinding() {
       constructor() {
         throw error;
       }
+      static openReadOnly() {
+        throw error;
+      }
+      static createEmptyReadOnly() {
+        throw error;
+      }
       close() {
         throw error;
       }
@@ -3882,6 +3888,12 @@ var VectorStore = class {
   load() {
     this.inner.load();
   }
+  loadStrict() {
+    this.inner.loadStrict();
+  }
+  hasFingerprint() {
+    return this.inner.hasFingerprint();
+  }
   count() {
     return this.inner.count();
   }
@@ -4164,12 +4176,24 @@ var InvertedIndex = class {
     return this.inner.documentCount();
   }
 };
-var Database = class {
+var Database = class _Database {
   inner;
   closed = false;
   constructor(dbPath) {
     this.inner = new native.Database(dbPath);
   }
+  static fromNative(inner) {
+    const database = Object.create(_Database.prototype);
+    database.inner = inner;
+    database.closed = false;
+    return database;
+  }
+  static openReadOnly(dbPath) {
+    return _Database.fromNative(native.Database.openReadOnly(dbPath));
+  }
+  static createEmptyReadOnly() {
+    return _Database.fromNative(native.Database.createEmptyReadOnly());
+  }
   throwIfClosed() {
     if (this.closed) {
       throw new Error("Database is closed");
@@ -4638,6 +4662,9 @@ function getHostProjectIndexRelativePath(host) {
 function hasHostProjectConfig(projectRoot, host) {
   return existsSync5(path8.join(projectRoot, getProjectConfigRelativePath(host)));
 }
+function hasHostGlobalConfig(host) {
+  return existsSync5(getGlobalConfigPath(host));
+}
 function getGlobalIndexPath(host = "opencode") {
   switch (host) {
     case "opencode":
@@ -4677,6 +4704,9 @@ function resolveGlobalIndexPath(host = "opencode") {
     return hostIndexPath;
   }
   if (host !== "opencode") {
+    if (hasHostGlobalConfig(host)) {
+      return hostIndexPath;
+    }
     const legacyIndexPath = getGlobalIndexPath("opencode");
     if (existsSync5(legacyIndexPath)) {
       return legacyIndexPath;
@@ -4893,6 +4923,432 @@ async function getChunkGitBlame(projectRoot, filePath, startLine, endLine) {
   }
 }
 
+// src/indexer/index-lock.ts
+import { randomUUID } from "crypto";
+import {
+  existsSync as existsSync6,
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync6,
+  readdirSync as readdirSync2,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import * as os4 from "os";
+import * as path11 from "path";
+var OWNER_FILE_NAME = "owner.json";
+var RECLAIM_DIRECTORY_NAME = "reclaiming";
+var RECOVERY_MARKER_PREFIX = "indexing.lock.recovery.";
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var VALID_OPERATIONS = /* @__PURE__ */ new Set([
+  "initialize",
+  "index",
+  "force-index",
+  "clear",
+  "health-check",
+  "retry-failed-batches",
+  "recovery"
+]);
+var temporaryCounter = 0;
+function getErrorCode(error) {
+  return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+}
+function retryTransientFilesystemOperation(operation) {
+  let lastError;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      operation();
+      return;
+    } catch (error) {
+      lastError = error;
+      const code = getErrorCode(error);
+      if (code !== "EBUSY" && code !== "EPERM") throw error;
+      if (attempt < 2) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, (attempt + 1) * 10);
+      }
+    }
+  }
+  throw lastError;
+}
+function parseOwner(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const candidate = value;
+  if (!Number.isInteger(candidate.pid) || (candidate.pid ?? 0) <= 0) return null;
+  if (typeof candidate.hostname !== "string" || candidate.hostname.length === 0) return null;
+  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;
+  return candidate;
+}
+function parseReclaimOwner(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const candidate = value;
+  if (!Number.isInteger(candidate.pid) || (candidate.pid ?? 0) <= 0) return null;
+  if (typeof candidate.hostname !== "string" || candidate.hostname.length === 0) return null;
+  if (typeof candidate.startedAt !== "string" || Number.isNaN(Date.parse(candidate.startedAt))) return null;
+  if (typeof candidate.token !== "string" || !UUID_PATTERN.test(candidate.token)) return null;
+  if (typeof candidate.expectedOwnerToken !== "string" || !UUID_PATTERN.test(candidate.expectedOwnerToken)) return null;
+  return candidate;
+}
+function readJsonDirectory(directoryPath, parser) {
+  try {
+    return parser(JSON.parse(readFileSync6(path11.join(directoryPath, OWNER_FILE_NAME), "utf-8")));
+  } catch {
+    return null;
+  }
+}
+function readDirectoryOwner(lockPath) {
+  return readJsonDirectory(lockPath, parseOwner);
+}
+function readReclaimOwner(markerPath) {
+  return readJsonDirectory(markerPath, parseReclaimOwner);
+}
+function readRecoveryOwner(markerPath) {
+  return readDirectoryOwner(markerPath);
+}
+function readLegacyOwner(lockPath) {
+  try {
+    const parsed = JSON.parse(readFileSync6(lockPath, "utf-8"));
+    if (!Number.isInteger(parsed.pid) || Number(parsed.pid) <= 0) return null;
+    if (typeof parsed.startedAt !== "string" || Number.isNaN(Date.parse(parsed.startedAt))) return null;
+    return {
+      pid: Number(parsed.pid),
+      hostname: typeof parsed.hostname === "string" ? parsed.hostname : os4.hostname(),
+      startedAt: parsed.startedAt,
+      operation: typeof parsed.operation === "string" && VALID_OPERATIONS.has(parsed.operation) ? parsed.operation : "index",
+      token: typeof parsed.token === "string" ? parsed.token : "legacy-v0.14.0"
+    };
+  } catch {
+    return null;
+  }
+}
+function getOwnerLiveness(owner) {
+  if (owner.hostname !== os4.hostname()) return "unknown";
+  try {
+    process.kill(owner.pid, 0);
+    return "alive";
+  } catch (error) {
+    const code = getErrorCode(error);
+    if (code === "ESRCH") return "dead";
+    if (code === "EPERM") return "alive";
+    return "unknown";
+  }
+}
+function sameOwner(left, right) {
+  return left.pid === right.pid && left.hostname === right.hostname && left.token === right.token;
+}
+function sameReclaimOwner(left, right) {
+  return left.pid === right.pid && left.hostname === right.hostname && left.token === right.token && left.expectedOwnerToken === right.expectedOwnerToken;
+}
+function publishJsonDirectory(finalPath, value) {
+  const candidatePath = `${finalPath}.candidate.${process.pid}.${randomUUID()}`;
+  mkdirSync2(candidatePath, { mode: 448 });
+  try {
+    writeFileSync2(path11.join(candidatePath, OWNER_FILE_NAME), JSON.stringify(value), {
+      encoding: "utf-8",
+      flag: "wx",
+      mode: 384
+    });
+    if (existsSync6(finalPath)) return false;
+    try {
+      renameSync(candidatePath, finalPath);
+      return true;
+    } catch (error) {
+      if (existsSync6(finalPath)) return false;
+      throw error;
+    }
+  } finally {
+    if (existsSync6(candidatePath)) rmSync(candidatePath, { recursive: true, force: true });
+  }
+}
+function createOwner(operation) {
+  return {
+    pid: process.pid,
+    hostname: os4.hostname(),
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    operation,
+    token: randomUUID()
+  };
+}
+function recoveryMarkerPath(indexPath, owner) {
+  return path11.join(indexPath, `${RECOVERY_MARKER_PREFIX}${owner.token}`);
+}
+function publishRecoveryMarker(indexPath, owner) {
+  const markerPath = recoveryMarkerPath(indexPath, owner);
+  if (!publishJsonDirectory(markerPath, owner)) {
+    const markerOwner = readRecoveryOwner(markerPath);
+    if (!markerOwner || !sameOwner(markerOwner, owner)) {
+      throw new IndexLockContentionError(markerPath, markerOwner, "unknown-owner");
+    }
+  }
+  return markerPath;
+}
+function getPendingRecoveries(indexPath) {
+  const recoveries = [];
+  const markerNames = readdirSync2(indexPath).filter((name) => {
+    if (!name.startsWith(RECOVERY_MARKER_PREFIX)) return false;
+    return UUID_PATTERN.test(name.slice(RECOVERY_MARKER_PREFIX.length));
+  }).sort();
+  for (const markerName of markerNames) {
+    const markerPath = path11.join(indexPath, markerName);
+    const markerToken = markerName.slice(RECOVERY_MARKER_PREFIX.length);
+    let markerStats;
+    try {
+      markerStats = lstatSync(markerPath);
+    } catch (error) {
+      if (getErrorCode(error) === "ENOENT") continue;
+      throw error;
+    }
+    if (!markerStats.isDirectory()) {
+      throw new IndexLockContentionError(markerPath, null, "unknown-owner");
+    }
+    const owner = readRecoveryOwner(markerPath);
+    if (!owner || owner.token !== markerToken || getOwnerLiveness(owner) !== "dead") {
+      throw new IndexLockContentionError(markerPath, owner, "unknown-owner");
+    }
+    recoveries.push({ owner, markerPath });
+  }
+  recoveries.sort((left, right) => {
+    const byTimestamp = left.owner.startedAt.localeCompare(right.owner.startedAt);
+    return byTimestamp !== 0 ? byTimestamp : left.markerPath.localeCompare(right.markerPath);
+  });
+  return recoveries;
+}
+function cleanupDeadPublicationCandidates(indexPath) {
+  const candidatePattern = /^indexing\.lock(?:\.recovery\.[0-9a-f-]{36})?\.candidate\.(\d+)\.[0-9a-f-]{36}$/i;
+  for (const entry of readdirSync2(indexPath)) {
+    const match = candidatePattern.exec(entry);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    if (getOwnerLiveness({ pid, hostname: os4.hostname() }) !== "dead") continue;
+    rmSync(path11.join(indexPath, entry), { recursive: true, force: true });
+  }
+}
+function removeDeadReclaimMarker(lockPath, expectedOwner) {
+  const markerPath = path11.join(lockPath, RECLAIM_DIRECTORY_NAME);
+  const marker = readReclaimOwner(markerPath);
+  if (!marker || marker.expectedOwnerToken !== expectedOwner.token || getOwnerLiveness(marker) !== "dead") {
+    return false;
+  }
+  const currentOwner = readDirectoryOwner(lockPath);
+  if (!currentOwner || !sameOwner(currentOwner, expectedOwner) || getOwnerLiveness(currentOwner) !== "dead") {
+    return false;
+  }
+  const claimedMarkerPath = `${markerPath}.stale.${marker.pid}.${marker.token}.${randomUUID()}`;
+  try {
+    renameSync(markerPath, claimedMarkerPath);
+  } catch (error) {
+    if (getErrorCode(error) === "ENOENT") return false;
+    throw error;
+  }
+  const claimedMarker = readReclaimOwner(claimedMarkerPath);
+  const ownerAfterClaim = readDirectoryOwner(lockPath);
+  if (!claimedMarker || !sameReclaimOwner(claimedMarker, marker) || !ownerAfterClaim || !sameOwner(ownerAfterClaim, expectedOwner) || getOwnerLiveness(ownerAfterClaim) !== "dead") {
+    if (!existsSync6(markerPath) && existsSync6(claimedMarkerPath)) {
+      renameSync(claimedMarkerPath, markerPath);
+    }
+    return false;
+  }
+  rmSync(claimedMarkerPath, { recursive: true, force: true });
+  return true;
+}
+function reclaimDeadOwner(indexPath, lockPath, expectedOwner) {
+  const reclaimPath = path11.join(lockPath, RECLAIM_DIRECTORY_NAME);
+  const reclaimOwner = {
+    pid: process.pid,
+    hostname: os4.hostname(),
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    token: randomUUID(),
+    expectedOwnerToken: expectedOwner.token
+  };
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    if (publishJsonDirectory(reclaimPath, reclaimOwner)) break;
+    if (attempt === 0 && removeDeadReclaimMarker(lockPath, expectedOwner)) continue;
+    return false;
+  }
+  try {
+    const currentReclaimer = readReclaimOwner(reclaimPath);
+    const currentOwner = readDirectoryOwner(lockPath);
+    if (!currentReclaimer || !sameReclaimOwner(currentReclaimer, reclaimOwner) || !currentOwner || !sameOwner(currentOwner, expectedOwner) || getOwnerLiveness(currentOwner) !== "dead") {
+      return false;
+    }
+    publishRecoveryMarker(indexPath, expectedOwner);
+    const ownerBeforeQuarantine = readDirectoryOwner(lockPath);
+    const reclaimerBeforeQuarantine = readReclaimOwner(reclaimPath);
+    if (!ownerBeforeQuarantine || !sameOwner(ownerBeforeQuarantine, expectedOwner) || getOwnerLiveness(ownerBeforeQuarantine) !== "dead" || !reclaimerBeforeQuarantine || !sameReclaimOwner(reclaimerBeforeQuarantine, reclaimOwner)) {
+      return false;
+    }
+    const quarantinePath = `${lockPath}.stale.${expectedOwner.token}.${reclaimOwner.token}`;
+    renameSync(lockPath, quarantinePath);
+    rmSync(quarantinePath, { recursive: true, force: true });
+    return true;
+  } catch (error) {
+    if (getErrorCode(error) === "ENOENT") return false;
+    throw error;
+  }
+}
+var IndexLockContentionError = class extends Error {
+  constructor(lockPath, owner, reason) {
+    const ownerDescription = owner ? `PID ${owner.pid} on ${owner.hostname}, operation ${owner.operation}, since ${owner.startedAt}` : "an unreadable owner";
+    super(`Index mutation already in progress: ${ownerDescription}`);
+    this.lockPath = lockPath;
+    this.owner = owner;
+    this.reason = reason;
+    this.name = "IndexLockContentionError";
+  }
+  lockPath;
+  owner;
+  reason;
+  code = "INDEX_BUSY";
+};
+function isIndexLockContentionError(error) {
+  return error instanceof IndexLockContentionError || typeof error === "object" && error !== null && "code" in error && error.code === "INDEX_BUSY";
+}
+function isTransientIndexLockContention(error) {
+  if (!isIndexLockContentionError(error) || !("reason" in error)) return false;
+  return error.reason === "active" || error.reason === "reclaiming";
+}
+function acquireIndexLock(indexPath, operation) {
+  mkdirSync2(indexPath, { recursive: true });
+  const canonicalIndexPath = realpathSync.native(indexPath);
+  const lockPath = path11.join(canonicalIndexPath, "indexing.lock");
+  cleanupDeadPublicationCandidates(canonicalIndexPath);
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    const owner = createOwner(operation);
+    if (publishJsonDirectory(lockPath, owner)) {
+      const lease = {
+        canonicalIndexPath,
+        lockPath,
+        owner,
+        recoveries: []
+      };
+      try {
+        lease.recoveries = getPendingRecoveries(canonicalIndexPath);
+        return lease;
+      } catch (error) {
+        releaseIndexLock(lease);
+        throw error;
+      }
+    }
+    let stats;
+    try {
+      stats = lstatSync(lockPath);
+    } catch (error) {
+      if (getErrorCode(error) === "ENOENT") continue;
+      throw error;
+    }
+    if (!stats.isDirectory()) {
+      const legacyOwner = readLegacyOwner(lockPath);
+      throw new IndexLockContentionError(lockPath, legacyOwner, "legacy-lock");
+    }
+    const existingOwner = readDirectoryOwner(lockPath);
+    if (!existingOwner) {
+      throw new IndexLockContentionError(lockPath, null, "unknown-owner");
+    }
+    const liveness = getOwnerLiveness(existingOwner);
+    if (liveness !== "dead") {
+      throw new IndexLockContentionError(lockPath, existingOwner, liveness === "alive" ? "active" : "unknown-owner");
+    }
+    if (!reclaimDeadOwner(canonicalIndexPath, lockPath, existingOwner)) {
+      throw new IndexLockContentionError(lockPath, existingOwner, "reclaiming");
+    }
+  }
+  throw new IndexLockContentionError(lockPath, null, "reclaiming");
+}
+function releaseIndexLock(lease) {
+  const currentOwner = readDirectoryOwner(lease.lockPath);
+  if (!currentOwner || !sameOwner(currentOwner, lease.owner)) return false;
+  const releasePath = `${lease.lockPath}.release.${lease.owner.pid}.${lease.owner.token}`;
+  try {
+    retryTransientFilesystemOperation(() => renameSync(lease.lockPath, releasePath));
+  } catch (error) {
+    if (getErrorCode(error) === "ENOENT") return false;
+    throw error;
+  }
+  const claimedOwner = readDirectoryOwner(releasePath);
+  if (!claimedOwner || !sameOwner(claimedOwner, lease.owner)) {
+    if (!existsSync6(lease.lockPath) && existsSync6(releasePath)) {
+      renameSync(releasePath, lease.lockPath);
+    }
+    return false;
+  }
+  try {
+    retryTransientFilesystemOperation(() => rmSync(releasePath, { recursive: true, force: true }));
+  } catch (error) {
+    console.error(`[codebase-index] Lease released but tombstone cleanup failed: ${releasePath}`, error);
+  }
+  return true;
+}
+async function withIndexLock(indexPath, operation, callback, options = {}) {
+  const lease = acquireIndexLock(indexPath, operation);
+  let result;
+  let callbackError;
+  let callbackFailed = false;
+  try {
+    result = await callback(lease);
+  } catch (error) {
+    callbackFailed = true;
+    callbackError = error;
+  }
+  if (!callbackFailed && options.completeRecoveries !== false) {
+    try {
+      completeLeaseRecovery(lease);
+    } catch (error) {
+      callbackFailed = true;
+      callbackError = error;
+    }
+  }
+  let releaseError;
+  try {
+    if (!releaseIndexLock(lease)) {
+      releaseError = new Error(`Lost ownership of index mutation lease ${lease.owner.token}`);
+    }
+  } catch (error) {
+    releaseError = error;
+  }
+  if (releaseError !== void 0) {
+    if (callbackFailed) throw new AggregateError([callbackError, releaseError], "Index mutation and lease release both failed");
+    throw releaseError;
+  }
+  if (callbackFailed) throw callbackError;
+  return result;
+}
+function createLeaseTemporaryPath(targetPath, owner, kind = "tmp") {
+  if (kind === "bak") return `${targetPath}.bak.${owner.pid}.${owner.token}`;
+  temporaryCounter += 1;
+  return `${targetPath}.tmp.${owner.pid}.${owner.token}.${temporaryCounter}`;
+}
+function removeLeaseTemporaryPath(temporaryPath) {
+  if (existsSync6(temporaryPath)) rmSync(temporaryPath, { recursive: true, force: true });
+}
+function recoverLeaseArtifacts(indexPath, owner, backupTargets) {
+  for (const targetPath of backupTargets) {
+    const backupPath = createLeaseTemporaryPath(targetPath, owner, "bak");
+    if (!existsSync6(backupPath)) continue;
+    if (existsSync6(targetPath)) rmSync(targetPath, { recursive: true, force: true });
+    renameSync(backupPath, targetPath);
+  }
+  const temporaryOwnerMarker = `.tmp.${owner.pid}.${owner.token}.`;
+  for (const entry of readdirSync2(indexPath)) {
+    if (!entry.includes(temporaryOwnerMarker)) continue;
+    rmSync(path11.join(indexPath, entry), { recursive: true, force: true });
+  }
+}
+function completeLeaseRecovery(lease) {
+  for (const recovery of lease.recoveries) {
+    const markerOwner = readRecoveryOwner(recovery.markerPath);
+    if (!markerOwner || !sameOwner(markerOwner, recovery.owner)) {
+      throw new Error(`Recovery marker ownership changed: ${recovery.markerPath}`);
+    }
+  }
+  for (const recovery of lease.recoveries) {
+    rmSync(recovery.markerPath, { recursive: true, force: true });
+  }
+}
+
 // src/indexer/index.ts
 var CALL_GRAPH_LANGUAGES = /* @__PURE__ */ new Set(["typescript", "tsx", "javascript", "jsx", "python", "go", "rust", "php", "apex", "zig", "gdscript", "matlab", "bash"]);
 var CASE_INSENSITIVE_LANGUAGES = /* @__PURE__ */ new Set(["apex"]);
@@ -4974,6 +5430,7 @@ function isSqliteCorruptionError(error) {
   return message.includes("database disk image is malformed") || message.includes("file is not a database") || message.includes("database schema is corrupt") || message.includes("sqlite_corrupt");
 }
 var STARTUP_WARNING_METADATA_KEY = "index.startupWarning";
+var READER_ARTIFACT_RETRY_INTERVAL_MS = 1e3;
 function metadataFromBlame(blame) {
   if (!blame) {
     return {};
@@ -5171,9 +5628,9 @@ function hasAllEmbeddingParts(parts, expectedPartCount) {
   return true;
 }
 function isPathWithinRoot(filePath, rootPath) {
-  const normalizedFilePath = path11.resolve(filePath);
-  const normalizedRoot = path11.resolve(rootPath);
-  return normalizedFilePath === normalizedRoot || normalizedFilePath.startsWith(`${normalizedRoot}${path11.sep}`);
+  const normalizedFilePath = path12.resolve(filePath);
+  const normalizedRoot = path12.resolve(rootPath);
+  return normalizedFilePath === normalizedRoot || normalizedFilePath.startsWith(`${normalizedRoot}${path12.sep}`);
 }
 var rankingQueryTokenCache = /* @__PURE__ */ new Map();
 var rankingNameTokenCache = /* @__PURE__ */ new Map();
@@ -6239,26 +6696,133 @@ var Indexer = class {
   queryCacheTtlMs = 5 * 60 * 1e3;
   querySimilarityThreshold = 0.85;
   indexCompatibility = null;
-  indexingLockPath = "";
+  activeIndexLease = null;
+  initializationPromise = null;
+  initializationMode = "none";
+  readIssues = [];
+  retiredDatabases = [];
+  readerArtifactFingerprint = null;
+  writerArtifactFingerprint = null;
+  readerArtifactRetryAfter = /* @__PURE__ */ new Map();
   constructor(projectRoot, config, host = "opencode") {
     this.projectRoot = projectRoot;
     this.config = config;
     this.host = host;
     this.indexPath = this.getIndexPath();
-    this.fileHashCachePath = path11.join(this.indexPath, "file-hashes.json");
-    this.failedBatchesPath = path11.join(this.indexPath, "failed-batches.json");
-    this.indexingLockPath = path11.join(this.indexPath, "indexing.lock");
+    this.fileHashCachePath = path12.join(this.indexPath, "file-hashes.json");
+    this.failedBatchesPath = path12.join(this.indexPath, "failed-batches.json");
     this.logger = initializeLogger(config.debug);
   }
   getIndexPath() {
     return resolveProjectIndexPath(this.projectRoot, this.config.scope, this.host);
   }
+  isLocalProjectIndexPath() {
+    const localProjectIndexPaths = [path12.join(this.projectRoot, getHostProjectIndexRelativePath(this.host))];
+    if (this.host !== "opencode") {
+      localProjectIndexPaths.push(path12.join(this.projectRoot, getHostProjectIndexRelativePath("opencode")));
+    }
+    return localProjectIndexPaths.some((localPath) => {
+      if (!existsSync7(localPath) || !existsSync7(this.indexPath)) {
+        return path12.resolve(this.indexPath) === path12.resolve(localPath);
+      }
+      const indexStats = statSync3(this.indexPath);
+      const localStats = statSync3(localPath);
+      return indexStats.dev === localStats.dev && indexStats.ino === localStats.ino;
+    });
+  }
+  resetLoadedIndexState(retireDatabase = false) {
+    if (this.database) {
+      if (retireDatabase) {
+        this.retiredDatabases.push(this.database);
+      } else {
+        this.database.close();
+      }
+    }
+    this.store = null;
+    this.invertedIndex = null;
+    this.database = null;
+    this.provider = null;
+    this.configuredProviderInfo = null;
+    this.reranker = null;
+    this.indexCompatibility = null;
+    this.initializationMode = "none";
+    this.readIssues = [];
+    this.readerArtifactFingerprint = null;
+    this.writerArtifactFingerprint = null;
+    this.readerArtifactRetryAfter.clear();
+    this.fileHashCache.clear();
+  }
+  refreshLoadedIndexState() {
+    if (!this.store || !this.invertedIndex || !this.configuredProviderInfo) return;
+    this.store.load();
+    this.invertedIndex.load();
+    this.fileHashCache.clear();
+    this.loadFileHashCache();
+    this.indexCompatibility = this.validateIndexCompatibility(this.configuredProviderInfo);
+    this.readIssues = [];
+    this.readerArtifactRetryAfter.clear();
+  }
+  async withIndexMutationLease(operation, callback) {
+    const lease = acquireIndexLock(this.indexPath, operation);
+    this.indexPath = lease.canonicalIndexPath;
+    this.fileHashCachePath = path12.join(this.indexPath, "file-hashes.json");
+    this.failedBatchesPath = path12.join(this.indexPath, "failed-batches.json");
+    this.activeIndexLease = lease;
+    let result;
+    let callbackError;
+    let callbackFailed = false;
+    try {
+      result = await callback(lease.recoveries.map(({ owner }) => owner));
+    } catch (error) {
+      callbackFailed = true;
+      callbackError = error;
+    }
+    if (!callbackFailed) {
+      try {
+        completeLeaseRecovery(lease);
+        this.writerArtifactFingerprint = this.captureReaderArtifactFingerprint();
+      } catch (error) {
+        callbackFailed = true;
+        callbackError = error;
+      }
+    }
+    let releaseError;
+    try {
+      if (!releaseIndexLock(lease)) {
+        releaseError = new Error(`Lost ownership of index mutation lease ${lease.owner.token}`);
+        this.writerArtifactFingerprint = null;
+        if (this.activeIndexLease?.owner.token === lease.owner.token) {
+          this.activeIndexLease = null;
+        }
+      } else if (this.activeIndexLease?.owner.token === lease.owner.token) {
+        this.activeIndexLease = null;
+      }
+    } catch (error) {
+      releaseError = error;
+      this.writerArtifactFingerprint = null;
+      if (!existsSync7(lease.lockPath) && this.activeIndexLease?.owner.token === lease.owner.token) {
+        this.activeIndexLease = null;
+      }
+    }
+    if (releaseError !== void 0) {
+      if (callbackFailed) throw new AggregateError([callbackError, releaseError], "Index mutation and lease release both failed");
+      throw releaseError;
+    }
+    if (callbackFailed) throw callbackError;
+    return result;
+  }
+  requireActiveLease() {
+    if (!this.activeIndexLease) {
+      throw new Error("Index mutation attempted without an active interprocess lease");
+    }
+    return this.activeIndexLease;
+  }
   loadFileHashCache() {
-    if (!existsSync6(this.fileHashCachePath)) {
+    if (!existsSync7(this.fileHashCachePath)) {
       return;
     }
     try {
-      const data = readFileSync6(this.fileHashCachePath, "utf-8");
+      const data = readFileSync7(this.fileHashCachePath, "utf-8");
       const parsed = JSON.parse(data);
       this.fileHashCache = new Map(Object.entries(parsed));
     } catch (error) {
@@ -6278,15 +6842,26 @@ var Indexer = class {
     this.atomicWriteSync(this.fileHashCachePath, JSON.stringify(obj));
   }
   atomicWriteSync(targetPath, data) {
-    const tempPath = `${targetPath}.tmp`;
-    mkdirSync2(path11.dirname(targetPath), { recursive: true });
-    writeFileSync2(tempPath, data);
-    renameSync(tempPath, targetPath);
+    const lease = this.requireActiveLease();
+    const tempPath = createLeaseTemporaryPath(targetPath, lease.owner, "tmp");
+    mkdirSync3(path12.dirname(targetPath), { recursive: true });
+    try {
+      writeFileSync3(tempPath, data);
+      renameSync2(tempPath, targetPath);
+    } finally {
+      removeLeaseTemporaryPath(tempPath);
+    }
+  }
+  saveInvertedIndex(invertedIndex) {
+    this.atomicWriteSync(
+      path12.join(this.indexPath, "inverted-index.json"),
+      invertedIndex.serialize()
+    );
   }
   getScopedRoots() {
-    const roots = /* @__PURE__ */ new Set([path11.resolve(this.projectRoot)]);
+    const roots = /* @__PURE__ */ new Set([path12.resolve(this.projectRoot)]);
     for (const kbRoot of this.config.knowledgeBases) {
-      roots.add(path11.resolve(this.projectRoot, kbRoot));
+      roots.add(path12.resolve(this.projectRoot, kbRoot));
     }
     return Array.from(roots);
   }
@@ -6295,29 +6870,29 @@ var Indexer = class {
     if (this.config.scope !== "global") {
       return branchName;
     }
-    const projectHash = hashContent(path11.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
     return `${projectHash}:${branchName}`;
   }
   getBranchCatalogKeyFor(branchName) {
     if (this.config.scope !== "global") {
       return branchName;
     }
-    const projectHash = hashContent(path11.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
     return `${projectHash}:${branchName}`;
   }
   getLegacyBranchCatalogKey() {
     return this.currentBranch || "default";
   }
   getLegacyMigrationMetadataKey() {
-    const projectHash = hashContent(path11.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
     return `index.globalBranchMigration.${projectHash}`;
   }
   getProjectEmbeddingStrategyMetadataKey() {
-    const projectHash = hashContent(path11.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
     return `index.embeddingStrategyVersion.${projectHash}`;
   }
   getProjectForceReembedMetadataKey() {
-    const projectHash = hashContent(path11.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
     return `index.forceReembed.${projectHash}`;
   }
   hasProjectForceReembedPending() {
@@ -6411,7 +6986,7 @@ var Indexer = class {
     if (!this.database) {
       return { chunkIds, symbolIds };
     }
-    const projectRootPath = path11.resolve(this.projectRoot);
+    const projectRootPath = path12.resolve(this.projectRoot);
     const projectLocalFilePaths = /* @__PURE__ */ new Set([
       ...Array.from(this.fileHashCache.keys()).filter(
         (filePath) => this.isFileInCurrentScope(filePath, roots) && isPathWithinRoot(filePath, projectRootPath)
@@ -6434,7 +7009,7 @@ var Indexer = class {
     if (this.config.scope !== "global") {
       return this.getBranchCatalogCleanupKeys();
     }
-    const projectHash = hashContent(path11.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
     const keys = /* @__PURE__ */ new Set();
     const projectChunkIdSet = new Set(projectChunkIds);
     const projectSymbolIdSet = new Set(projectSymbolIds);
@@ -6518,7 +7093,7 @@ var Indexer = class {
     if (!this.database || this.config.scope !== "global") {
       return false;
     }
-    const projectHash = hashContent(path11.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
     const roots = this.getScopedRoots();
     const { chunkIds: projectLocalChunkIds, symbolIds: projectLocalSymbolIds } = this.getProjectLocalScopedOwnershipIds(roots);
     return this.database.getAllBranches().some(
@@ -6552,7 +7127,7 @@ var Indexer = class {
       ...Array.from(this.fileHashCache.keys()).filter((filePath) => this.isFileInCurrentScope(filePath, roots)),
       ...scopedEntries.map(({ metadata }) => metadata.filePath)
     ]);
-    const projectRootPath = path11.resolve(this.projectRoot);
+    const projectRootPath = path12.resolve(this.projectRoot);
     const projectLocalFilePaths = new Set(
       Array.from(filePaths).filter((filePath) => isPathWithinRoot(filePath, projectRootPath))
     );
@@ -6614,34 +7189,27 @@ var Indexer = class {
     database.gcOrphanEmbeddings();
     database.gcOrphanChunks();
     store.save();
-    invertedIndex.save();
+    this.saveInvertedIndex(invertedIndex);
     return {
       removedChunkIds: removedChunkIdList,
       hasForeignData: allMetadata.some(({ metadata }) => !this.isFileInCurrentScope(metadata.filePath, roots))
     };
   }
-  checkForInterruptedIndexing() {
-    return existsSync6(this.indexingLockPath);
-  }
-  acquireIndexingLock() {
-    const lockData = {
-      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      pid: process.pid
-    };
-    writeFileSync2(this.indexingLockPath, JSON.stringify(lockData));
-  }
-  releaseIndexingLock() {
-    if (existsSync6(this.indexingLockPath)) {
-      unlinkSync(this.indexingLockPath);
+  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
+      });
     }
-  }
-  async recoverFromInterruptedIndexing() {
-    this.logger.warn("Detected interrupted indexing session, recovering...");
-    if (existsSync6(this.fileHashCachePath)) {
-      unlinkSync(this.fileHashCachePath);
+    if (this.config.scope === "global") {
+      if (existsSync7(this.fileHashCachePath)) {
+        unlinkSync(this.fileHashCachePath);
+      }
+      await this.healthCheckUnlocked();
     }
-    await this.healthCheck();
-    this.releaseIndexingLock();
     this.logger.info("Recovery complete, next index will re-process all files");
   }
   loadFailedBatches(maxChunkTokens) {
@@ -6657,10 +7225,10 @@ var Indexer = class {
     }
   }
   loadSerializedFailedBatches() {
-    if (!existsSync6(this.failedBatchesPath)) {
+    if (!existsSync7(this.failedBatchesPath)) {
       return [];
     }
-    const data = readFileSync6(this.failedBatchesPath, "utf-8");
+    const data = readFileSync7(this.failedBatchesPath, "utf-8");
     const parsed = JSON.parse(data);
     return parsed.map((batch) => {
       const chunks = Array.isArray(batch.chunks) ? batch.chunks : [];
@@ -6677,7 +7245,7 @@ var Indexer = class {
   }
   saveFailedBatches(batches) {
     if (batches.length === 0) {
-      if (existsSync6(this.failedBatchesPath)) {
+      if (existsSync7(this.failedBatchesPath)) {
         try {
           unlinkSync(this.failedBatchesPath);
         } catch {
@@ -6685,7 +7253,7 @@ var Indexer = class {
       }
       return;
     }
-    writeFileSync2(this.failedBatchesPath, JSON.stringify(batches, null, 2));
+    this.atomicWriteSync(this.failedBatchesPath, JSON.stringify(batches, null, 2));
   }
   collectRetryableFailedChunks(currentFileHashes, unchangedFilePaths, maxChunkTokens) {
     const retryableById = /* @__PURE__ */ new Map();
@@ -6879,6 +7447,222 @@ var Indexer = class {
     return parts.join("\n");
   }
   async initialize() {
+    if (this.initializationPromise) {
+      await this.initializationPromise;
+    }
+    if (this.isInitializedFor("reader")) {
+      return;
+    }
+    await this.initializeOnce("reader", [], { skipAutoGc: true });
+  }
+  async initializeOnce(mode, recoveredOwners, options) {
+    if (this.initializationPromise) {
+      await this.initializationPromise;
+      if (this.isInitializedFor(mode)) {
+        return;
+      }
+      return this.initializeOnce(mode, recoveredOwners, options);
+    }
+    if (this.isInitializedFor(mode)) {
+      return;
+    }
+    const initialization = this.initializeUnlocked(mode, recoveredOwners, options).catch((error) => {
+      this.resetLoadedIndexState();
+      throw error;
+    }).finally(() => {
+      if (this.initializationPromise === initialization) {
+        this.initializationPromise = null;
+      }
+    });
+    this.initializationPromise = initialization;
+    await initialization;
+  }
+  isInitializedFor(mode) {
+    const hasState = Boolean(
+      this.store && this.provider && this.invertedIndex && this.configuredProviderInfo && this.database
+    );
+    if (!hasState) {
+      return false;
+    }
+    return mode === "reader" ? this.initializationMode !== "none" : this.initializationMode === "writer";
+  }
+  recordReadIssue(component, message, error) {
+    this.readIssues.push(this.createReadIssue(component, message));
+    this.readerArtifactRetryAfter.set(component, Date.now() + READER_ARTIFACT_RETRY_INTERVAL_MS);
+    this.logger.warn(message, error === void 0 ? void 0 : { error: getErrorMessage2(error) });
+  }
+  createReadIssue(component, message) {
+    return {
+      component,
+      message,
+      blocking: component !== "keyword"
+    };
+  }
+  getVectorReadIssueMessage() {
+    if (this.config.scope === "global") {
+      return "Shared vector index could not be read. Restore or repair the complete fingerprinted shared vector artifacts; automatic reset is disabled for global scope.";
+    }
+    if (!this.isLocalProjectIndexPath()) {
+      return "Vector index could not be read from an inherited project index. Restore or fingerprint it from the checkout that owns the index; do not remove or rebuild it from this worktree.";
+    }
+    return "Vector index could not be read. Run index_codebase after the active writer finishes to fingerprint a structurally valid legacy pair, or remove this checkout's local index directory and run index_codebase to rebuild it.";
+  }
+  getKeywordReadIssueMessage() {
+    if (this.config.scope === "global") {
+      return "Shared keyword index could not be read; semantic search remains available. Restore or repair the shared keyword artifact; automatic reset is disabled for global scope.";
+    }
+    if (!this.isLocalProjectIndexPath()) {
+      return "Keyword index could not be read from an inherited project index; semantic search remains available. Restore or repair it from the checkout that owns the index; do not rebuild it from this worktree.";
+    }
+    return "Keyword index could not be read; semantic search remains available. Restore a readable published keyword index, or run index_codebase with force=true after the active writer finishes.";
+  }
+  getDatabaseReadIssueMessage() {
+    if (this.config.scope === "global") {
+      return "Shared index database could not be read. Restore or repair the shared SQLite database; automatic reset is disabled for global scope.";
+    }
+    if (!this.isLocalProjectIndexPath()) {
+      return "Index database could not be read from an inherited project index. Restore or repair it from the checkout that owns the index; do not migrate or rebuild it from this worktree.";
+    }
+    return "Index database could not be read. Run index_codebase after the active writer finishes to repair or migrate it under the writer lease.";
+  }
+  getReaderFileFingerprint(filePath, identityOnly = false) {
+    try {
+      const stats = statSync3(filePath);
+      if (identityOnly) {
+        return `${stats.dev}:${stats.ino}`;
+      }
+      return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`;
+    } catch (error) {
+      return `unavailable:${getErrorMessage2(error)}`;
+    }
+  }
+  captureReaderArtifactFingerprint() {
+    const storePath = path12.join(this.indexPath, "vectors");
+    return {
+      vectors: `${this.getReaderFileFingerprint(storePath)}|${this.getReaderFileFingerprint(`${storePath}.meta.json`)}`,
+      keyword: this.getReaderFileFingerprint(path12.join(this.indexPath, "inverted-index.json")),
+      database: this.getReaderFileFingerprint(path12.join(this.indexPath, "codebase.db")),
+      databaseIdentity: this.getReaderFileFingerprint(path12.join(this.indexPath, "codebase.db"), true)
+    };
+  }
+  refreshReaderArtifacts() {
+    if (this.initializationMode !== "reader" || !this.configuredProviderInfo) {
+      return;
+    }
+    const previousFingerprint = this.readerArtifactFingerprint;
+    const currentFingerprint = this.captureReaderArtifactFingerprint();
+    const issues = new Map(this.readIssues.map((issue) => [issue.component, issue]));
+    const retryDue = (component) => issues.has(component) && Date.now() >= (this.readerArtifactRetryAfter.get(component) ?? 0);
+    const vectorsChanged = !previousFingerprint || currentFingerprint.vectors !== previousFingerprint.vectors;
+    const keywordChanged = !previousFingerprint || currentFingerprint.keyword !== previousFingerprint.keyword;
+    const databaseChanged = !previousFingerprint || currentFingerprint.database !== previousFingerprint.database;
+    const databaseReplaced = !previousFingerprint || currentFingerprint.databaseIdentity !== previousFingerprint.databaseIdentity;
+    if (previousFingerprint && !vectorsChanged && !keywordChanged && !databaseChanged && !Array.from(issues.keys()).some(retryDue)) {
+      return;
+    }
+    const setIssue = (component, message, error) => {
+      if (!issues.has(component)) {
+        this.logger.warn(message, error === void 0 ? void 0 : { error: getErrorMessage2(error) });
+      }
+      issues.set(component, this.createReadIssue(component, message));
+      this.readerArtifactRetryAfter.set(component, Date.now() + READER_ARTIFACT_RETRY_INTERVAL_MS);
+    };
+    const storePath = path12.join(this.indexPath, "vectors");
+    const vectorMetadataPath = `${storePath}.meta.json`;
+    const invertedIndexPath = path12.join(this.indexPath, "inverted-index.json");
+    const dbPath = path12.join(this.indexPath, "codebase.db");
+    if (vectorsChanged || retryDue("vectors")) {
+      const vectorStoreExists = existsSync7(storePath);
+      const vectorMetadataExists = existsSync7(vectorMetadataPath);
+      if (vectorStoreExists && vectorMetadataExists) {
+        try {
+          const store = new VectorStore(storePath, this.configuredProviderInfo.modelInfo.dimensions);
+          store.loadStrict();
+          this.store = store;
+          issues.delete("vectors");
+          this.readerArtifactRetryAfter.delete("vectors");
+        } catch (error) {
+          setIssue("vectors", this.getVectorReadIssueMessage(), error);
+        }
+      } else if (vectorStoreExists !== vectorMetadataExists || issues.has("vectors")) {
+        setIssue("vectors", this.getVectorReadIssueMessage());
+      }
+    }
+    if (keywordChanged || retryDue("keyword") || !existsSync7(invertedIndexPath) && (this.store?.count() ?? 0) > 0) {
+      if (existsSync7(invertedIndexPath)) {
+        try {
+          const invertedIndex = new InvertedIndex(invertedIndexPath);
+          invertedIndex.load();
+          this.invertedIndex = invertedIndex;
+          issues.delete("keyword");
+          this.readerArtifactRetryAfter.delete("keyword");
+        } catch (error) {
+          setIssue("keyword", this.getKeywordReadIssueMessage(), error);
+        }
+      } else if ((this.store?.count() ?? 0) > 0 || issues.has("keyword")) {
+        setIssue("keyword", this.getKeywordReadIssueMessage());
+      }
+    }
+    if (databaseReplaced || databaseChanged && issues.has("database") || retryDue("database")) {
+      if (existsSync7(dbPath)) {
+        try {
+          const database = Database.openReadOnly(dbPath);
+          if (this.database) {
+            this.retiredDatabases.push(this.database);
+          }
+          this.database = database;
+          issues.delete("database");
+          this.readerArtifactRetryAfter.delete("database");
+        } catch (error) {
+          setIssue("database", this.getDatabaseReadIssueMessage(), error);
+        }
+      } else if ((this.store?.count() ?? 0) > 0 || issues.has("database")) {
+        setIssue("database", this.getDatabaseReadIssueMessage());
+      }
+    }
+    if (!issues.has("database")) {
+      try {
+        this.indexCompatibility = this.validateIndexCompatibility(this.configuredProviderInfo);
+      } catch (error) {
+        setIssue("database", this.getDatabaseReadIssueMessage(), error);
+      }
+    }
+    this.readIssues = Array.from(issues.values());
+    this.readerArtifactFingerprint = currentFingerprint;
+  }
+  refreshInactiveWriterArtifacts() {
+    if (this.initializationMode !== "writer" || this.activeIndexLease) {
+      return true;
+    }
+    const previousFingerprint = this.writerArtifactFingerprint;
+    const currentFingerprint = this.captureReaderArtifactFingerprint();
+    const retryDue = this.readIssues.some(
+      (issue) => Date.now() >= (this.readerArtifactRetryAfter.get(issue.component) ?? 0)
+    );
+    const artifactsChanged = !previousFingerprint || currentFingerprint.vectors !== previousFingerprint.vectors || currentFingerprint.keyword !== previousFingerprint.keyword || currentFingerprint.database !== previousFingerprint.database || currentFingerprint.databaseIdentity !== previousFingerprint.databaseIdentity;
+    if (!artifactsChanged && !retryDue) {
+      return true;
+    }
+    if (!previousFingerprint || currentFingerprint.databaseIdentity !== previousFingerprint.databaseIdentity) {
+      return false;
+    }
+    this.initializationMode = "reader";
+    this.readerArtifactFingerprint = previousFingerprint;
+    try {
+      this.refreshReaderArtifacts();
+      this.writerArtifactFingerprint = this.readerArtifactFingerprint ?? currentFingerprint;
+    } finally {
+      this.readerArtifactFingerprint = null;
+      this.initializationMode = "writer";
+    }
+    return true;
+  }
+  async initializeUnlocked(mode, recoveredOwners = [], options = {}) {
+    if (mode === "writer") {
+      this.requireActiveLease();
+    }
+    this.readIssues = [];
+    this.readerArtifactRetryAfter.clear();
     if (this.config.embeddingProvider === "custom") {
       if (!this.config.customProvider) {
         throw new Error("embeddingProvider is 'custom' but customProvider config is missing.");
@@ -6910,36 +7694,103 @@ var Indexer = class {
         });
       }
     }
-    await fsPromises2.mkdir(this.indexPath, { recursive: true });
     const dimensions = this.configuredProviderInfo.modelInfo.dimensions;
-    const storePath = path11.join(this.indexPath, "vectors");
-    this.store = new VectorStore(storePath, dimensions);
-    const indexFilePath = path11.join(this.indexPath, "vectors.usearch");
-    if (existsSync6(indexFilePath)) {
-      this.store.load();
-    }
-    const invertedIndexPath = path11.join(this.indexPath, "inverted-index.json");
-    this.invertedIndex = new InvertedIndex(invertedIndexPath);
-    try {
-      this.invertedIndex.load();
-    } catch {
-      if (existsSync6(invertedIndexPath)) {
-        await fsPromises2.unlink(invertedIndexPath);
+    const storePath = path12.join(this.indexPath, "vectors");
+    const vectorMetadataPath = `${storePath}.meta.json`;
+    const invertedIndexPath = path12.join(this.indexPath, "inverted-index.json");
+    const dbPath = path12.join(this.indexPath, "codebase.db");
+    let dbIsNew = !existsSync7(dbPath);
+    const readerArtifactFingerprint = mode === "reader" ? this.captureReaderArtifactFingerprint() : null;
+    if (mode === "writer") {
+      await fsPromises2.mkdir(this.indexPath, { recursive: true });
+      if (recoveredOwners.length > 0 && this.config.scope === "project" && !this.isLocalProjectIndexPath()) {
+        throw new Error(
+          "Interrupted indexing recovery is unsafe while using an inherited worktree index. Run index_codebase with force=true to create a local project index boundary."
+        );
+      }
+      for (const recoveredOwner of recoveredOwners) {
+        recoverLeaseArtifacts(this.indexPath, recoveredOwner, [
+          storePath,
+          `${storePath}.meta.json`
+        ]);
+      }
+      if (recoveredOwners.length > 0 && this.config.scope === "project") {
+        await this.resetLocalIndexArtifacts();
+      }
+      this.store = new VectorStore(storePath, dimensions);
+      if (existsSync7(storePath) || existsSync7(vectorMetadataPath)) {
+        this.store.load();
       }
       this.invertedIndex = new InvertedIndex(invertedIndexPath);
-    }
-    const dbPath = path11.join(this.indexPath, "codebase.db");
-    let dbIsNew = !existsSync6(dbPath);
-    try {
-      this.database = new Database(dbPath);
-    } catch (error) {
-      if (!await this.tryResetCorruptedIndex("initializing index database", error)) {
-        throw error;
+      try {
+        this.invertedIndex.load();
+      } catch {
+        if (existsSync7(invertedIndexPath)) {
+          await fsPromises2.unlink(invertedIndexPath);
+        }
+        this.invertedIndex = new InvertedIndex(invertedIndexPath);
+      }
+      try {
+        this.database = new Database(dbPath);
+      } catch (error) {
+        if (!await this.tryResetCorruptedIndex("initializing index database", error)) {
+          throw error;
+        }
+        this.store = new VectorStore(storePath, dimensions);
+        this.invertedIndex = new InvertedIndex(invertedIndexPath);
+        this.database = new Database(dbPath);
+        dbIsNew = true;
       }
+    } else {
       this.store = new VectorStore(storePath, dimensions);
+      const vectorStoreExists = existsSync7(storePath);
+      const vectorMetadataExists = existsSync7(vectorMetadataPath);
+      const vectorReadFailureMessage = this.getVectorReadIssueMessage();
+      if (vectorStoreExists !== vectorMetadataExists) {
+        this.recordReadIssue("vectors", vectorReadFailureMessage);
+      } else if (vectorStoreExists) {
+        try {
+          this.store.loadStrict();
+        } catch (error) {
+          this.recordReadIssue("vectors", vectorReadFailureMessage, error);
+          this.store = new VectorStore(storePath, dimensions);
+        }
+      }
       this.invertedIndex = new InvertedIndex(invertedIndexPath);
-      this.database = new Database(dbPath);
-      dbIsNew = true;
+      if (existsSync7(invertedIndexPath)) {
+        try {
+          this.invertedIndex.load();
+        } catch (error) {
+          this.recordReadIssue(
+            "keyword",
+            this.getKeywordReadIssueMessage(),
+            error
+          );
+          this.invertedIndex = new InvertedIndex(invertedIndexPath);
+        }
+      } else if (this.store.count() > 0) {
+        this.recordReadIssue("keyword", this.getKeywordReadIssueMessage());
+      }
+      if (existsSync7(dbPath)) {
+        try {
+          this.database = Database.openReadOnly(dbPath);
+        } catch (error) {
+          this.recordReadIssue(
+            "database",
+            this.getDatabaseReadIssueMessage(),
+            error
+          );
+          this.database = Database.createEmptyReadOnly();
+        }
+      } else {
+        this.database = Database.createEmptyReadOnly();
+        if (this.store.count() > 0) {
+          this.recordReadIssue(
+            "database",
+            `Index database is missing for the published vectors. ${this.getDatabaseReadIssueMessage()}`
+          );
+        }
+      }
     }
     if (isGitRepo(this.projectRoot)) {
       this.currentBranch = getBranchOrDefault(this.projectRoot);
@@ -6953,10 +7804,10 @@ var Indexer = class {
       this.baseBranch = "default";
       this.logger.branch("debug", "Not a git repository, using default branch");
     }
-    if (this.checkForInterruptedIndexing()) {
-      await this.recoverFromInterruptedIndexing();
+    if (mode === "writer" && recoveredOwners.length > 0) {
+      await this.recoverFromInterruptedIndexingUnlocked(recoveredOwners);
     }
-    if (dbIsNew && this.store.count() > 0) {
+    if (mode === "writer" && dbIsNew && this.store.count() > 0) {
       this.migrateFromLegacyIndex();
     }
     this.loadFileHashCache();
@@ -6968,9 +7819,11 @@ var Indexer = class {
         configuredProviderInfo: this.configuredProviderInfo
       });
     }
-    if (this.config.indexing.autoGc) {
+    if (mode === "writer" && this.config.indexing.autoGc && !options.skipAutoGc) {
       await this.maybeRunAutoGc();
     }
+    this.initializationMode = mode;
+    this.readerArtifactFingerprint = readerArtifactFingerprint;
   }
   async maybeRunAutoGc() {
     if (!this.database) return;
@@ -6987,7 +7840,7 @@ var Indexer = class {
       }
     }
     if (shouldRunGc) {
-      const result = await this.healthCheck();
+      const result = await this.healthCheckUnlocked();
       if (result.warning) {
         this.database.setMetadata(STARTUP_WARNING_METADATA_KEY, result.warning);
       } else {
@@ -7009,7 +7862,7 @@ var Indexer = class {
         if (await this.tryResetCorruptedIndex("running automatic orphan garbage collection", error)) {
           return {
             resetCorruptedIndex: true,
-            warning: this.getCorruptedIndexWarning(path11.join(this.indexPath, "codebase.db"))
+            warning: this.getCorruptedIndexWarning(path12.join(this.indexPath, "codebase.db"))
           };
         }
         throw error;
@@ -7024,28 +7877,29 @@ var Indexer = class {
       return;
     }
     const retainedEntries = store.getAllMetadata().filter(({ key }) => !excludedSet.has(key));
-    const storeBasePath = path11.join(this.indexPath, "vectors");
-    const storeIndexPath = `${storeBasePath}.usearch`;
+    const storeBasePath = path12.join(this.indexPath, "vectors");
+    const storeIndexPath = storeBasePath;
     const storeMetadataPath = `${storeBasePath}.meta.json`;
-    const backupIndexPath = `${storeIndexPath}.bak`;
-    const backupMetadataPath = `${storeMetadataPath}.bak`;
+    const lease = this.requireActiveLease();
+    const backupIndexPath = createLeaseTemporaryPath(storeIndexPath, lease.owner, "bak");
+    const backupMetadataPath = createLeaseTemporaryPath(storeMetadataPath, lease.owner, "bak");
     let backedUpIndex = false;
     let backedUpMetadata = false;
     let rebuiltCount = 0;
     let skippedCount = 0;
-    if (existsSync6(backupIndexPath)) {
+    if (existsSync7(backupIndexPath)) {
       unlinkSync(backupIndexPath);
     }
-    if (existsSync6(backupMetadataPath)) {
+    if (existsSync7(backupMetadataPath)) {
       unlinkSync(backupMetadataPath);
     }
     try {
-      if (existsSync6(storeIndexPath)) {
-        renameSync(storeIndexPath, backupIndexPath);
+      if (existsSync7(storeIndexPath)) {
+        renameSync2(storeIndexPath, backupIndexPath);
         backedUpIndex = true;
       }
-      if (existsSync6(storeMetadataPath)) {
-        renameSync(storeMetadataPath, backupMetadataPath);
+      if (existsSync7(storeMetadataPath)) {
+        renameSync2(storeMetadataPath, backupMetadataPath);
         backedUpMetadata = true;
       }
       store.clear();
@@ -7065,10 +7919,10 @@ var Indexer = class {
         rebuiltCount += 1;
       }
       store.save();
-      if (backedUpIndex && existsSync6(backupIndexPath)) {
+      if (backedUpIndex && existsSync7(backupIndexPath)) {
         unlinkSync(backupIndexPath);
       }
-      if (backedUpMetadata && existsSync6(backupMetadataPath)) {
+      if (backedUpMetadata && existsSync7(backupMetadataPath)) {
         unlinkSync(backupMetadataPath);
       }
       this.logger.gc("info", "Rebuilt vector store to avoid native remove", {
@@ -7081,17 +7935,17 @@ var Indexer = class {
         store.clear();
       } catch {
       }
-      if (existsSync6(storeIndexPath)) {
+      if (existsSync7(storeIndexPath)) {
         unlinkSync(storeIndexPath);
       }
-      if (existsSync6(storeMetadataPath)) {
+      if (existsSync7(storeMetadataPath)) {
         unlinkSync(storeMetadataPath);
       }
-      if (backedUpIndex && existsSync6(backupIndexPath)) {
-        renameSync(backupIndexPath, storeIndexPath);
+      if (backedUpIndex && existsSync7(backupIndexPath)) {
+        renameSync2(backupIndexPath, storeIndexPath);
       }
-      if (backedUpMetadata && existsSync6(backupMetadataPath)) {
-        renameSync(backupMetadataPath, storeMetadataPath);
+      if (backedUpMetadata && existsSync7(backupMetadataPath)) {
+        renameSync2(backupMetadataPath, storeMetadataPath);
       }
       if (backedUpIndex || backedUpMetadata) {
         store.load();
@@ -7105,11 +7959,37 @@ var Indexer = class {
     }
     return `Detected a corrupted local SQLite index at ${dbPath} and reset the local index. Run index_codebase to rebuild search data.`;
   }
+  async resetLocalIndexArtifacts() {
+    this.store = null;
+    this.invertedIndex = null;
+    this.database?.close();
+    this.database = null;
+    this.indexCompatibility = null;
+    this.initializationMode = "none";
+    this.readIssues = [];
+    this.readerArtifactFingerprint = null;
+    this.writerArtifactFingerprint = null;
+    this.readerArtifactRetryAfter.clear();
+    this.fileHashCache.clear();
+    const resetPaths = [
+      path12.join(this.indexPath, "codebase.db"),
+      path12.join(this.indexPath, "codebase.db-shm"),
+      path12.join(this.indexPath, "codebase.db-wal"),
+      path12.join(this.indexPath, "vectors"),
+      path12.join(this.indexPath, "vectors.usearch"),
+      path12.join(this.indexPath, "vectors.meta.json"),
+      path12.join(this.indexPath, "inverted-index.json"),
+      path12.join(this.indexPath, "file-hashes.json"),
+      path12.join(this.indexPath, "failed-batches.json")
+    ];
+    await Promise.all(resetPaths.map((targetPath) => fsPromises2.rm(targetPath, { recursive: true, force: true })));
+    await fsPromises2.mkdir(this.indexPath, { recursive: true });
+  }
   async tryResetCorruptedIndex(stage, error) {
     if (!isSqliteCorruptionError(error)) {
       return false;
     }
-    const dbPath = path11.join(this.indexPath, "codebase.db");
+    const dbPath = path12.join(this.indexPath, "codebase.db");
     const warning = this.getCorruptedIndexWarning(dbPath);
     const errorMessage = getErrorMessage2(error);
     if (this.config.scope === "global") {
@@ -7125,30 +8005,7 @@ var Indexer = class {
       dbPath,
       error: errorMessage
     });
-    this.store = null;
-    this.invertedIndex = null;
-    this.database?.close();
-    this.database = null;
-    this.indexCompatibility = null;
-    this.fileHashCache.clear();
-    const resetPaths = [
-      path11.join(this.indexPath, "codebase.db"),
-      path11.join(this.indexPath, "codebase.db-shm"),
-      path11.join(this.indexPath, "codebase.db-wal"),
-      path11.join(this.indexPath, "vectors.usearch"),
-      path11.join(this.indexPath, "inverted-index.json"),
-      path11.join(this.indexPath, "file-hashes.json"),
-      path11.join(this.indexPath, "failed-batches.json"),
-      path11.join(this.indexPath, "indexing.lock"),
-      path11.join(this.indexPath, "vectors")
-    ];
-    await Promise.all(resetPaths.map(async (targetPath) => {
-      try {
-        await fsPromises2.rm(targetPath, { recursive: true, force: true });
-      } catch {
-      }
-    }));
-    await fsPromises2.mkdir(this.indexPath, { recursive: true });
+    await this.resetLocalIndexArtifacts();
     return true;
   }
   migrateFromLegacyIndex() {
@@ -7267,8 +8124,62 @@ var Indexer = class {
     return this.indexCompatibility;
   }
   async ensureInitialized() {
+    let initializedReader = false;
+    while (true) {
+      if (this.initializationPromise) {
+        await this.initializationPromise;
+      }
+      if (!this.isInitializedFor("reader")) {
+        await this.initialize();
+        initializedReader = true;
+        continue;
+      }
+      if (this.initializationMode === "writer" && !this.activeIndexLease && !initializedReader) {
+        if (!this.refreshInactiveWriterArtifacts()) {
+          this.resetLoadedIndexState(true);
+          await this.initialize();
+          initializedReader = true;
+          continue;
+        }
+      }
+      if (this.initializationMode === "reader" && !initializedReader) {
+        this.refreshReaderArtifacts();
+      }
+      const state = this.requireLoadedIndexState();
+      return {
+        ...state,
+        readIssues: [...this.readIssues],
+        compatibility: this.indexCompatibility ?? this.validateIndexCompatibility(state.configuredProviderInfo)
+      };
+    }
+  }
+  async ensureInitializedUnlocked(recoveredOwners = []) {
+    this.requireActiveLease();
+    if (this.initializationPromise) {
+      await this.initializationPromise;
+    }
+    if (recoveredOwners.length > 0 || !this.isInitializedFor("writer")) {
+      const retireReaderDatabase = this.initializationMode === "reader";
+      this.resetLoadedIndexState(retireReaderDatabase);
+      await this.initializeOnce("writer", recoveredOwners, { skipAutoGc: true });
+    } else {
+      this.refreshLoadedIndexState();
+    }
+    if (this.config.indexing.autoGc) {
+      await this.maybeRunAutoGc();
+    }
+    return this.requireLoadedIndexState();
+  }
+  requireReadableComponents(readIssues, ...components) {
+    const componentSet = new Set(components);
+    const issues = readIssues.filter((issue) => issue.blocking && componentSet.has(issue.component));
+    if (issues.length > 0) {
+      throw new Error(issues.map((issue) => issue.message).join(" "));
+    }
+  }
+  requireLoadedIndexState() {
     if (!this.store || !this.provider || !this.invertedIndex || !this.configuredProviderInfo || !this.database) {
-      await this.initialize();
+      throw new Error("Index state is not initialized");
     }
     return {
       store: this.store,
@@ -7292,7 +8203,12 @@ var Indexer = class {
     return createCostEstimate(files, configuredProviderInfo);
   }
   async index(onProgress) {
-    const { store, provider, invertedIndex, database, configuredProviderInfo } = await this.ensureInitialized();
+    return this.withIndexMutationLease("index", async (recoveredOwners) => {
+      return this.indexUnlocked(onProgress, recoveredOwners);
+    });
+  }
+  async indexUnlocked(onProgress, recoveredOwners = [], stateReady = false) {
+    const { store, provider, invertedIndex, database, configuredProviderInfo } = stateReady ? this.requireLoadedIndexState() : await this.ensureInitializedUnlocked(recoveredOwners);
     const scopedRoots = this.config.scope === "global" ? this.getScopedRoots() : null;
     const branchCatalogKey = this.getBranchCatalogKey();
     const forceScopedReembed = scopedRoots !== null && database.getMetadata(this.getProjectForceReembedMetadataKey()) === "true";
@@ -7302,7 +8218,6 @@ var Indexer = class {
         `${this.indexCompatibility?.reason} Run index_codebase with force=true to rebuild the index.`
       );
     }
-    this.acquireIndexingLock();
     this.logger.recordIndexingStart();
     this.logger.info("Starting indexing", { projectRoot: this.projectRoot });
     const startTime = Date.now();
@@ -7451,7 +8366,7 @@ var Indexer = class {
     for (const parsed of parsedFiles) {
       currentFilePaths.add(parsed.path);
       if (parsed.chunks.length === 0) {
-        const relativePath = path11.relative(this.projectRoot, parsed.path);
+        const relativePath = path12.relative(this.projectRoot, parsed.path);
         stats.parseFailures.push(relativePath);
       }
       let fileChunkCount = 0;
@@ -7651,7 +8566,9 @@ var Indexer = class {
       database.addChunksToBranchBatch(branchCatalogKey, Array.from(currentChunkIds));
       database.clearBranchSymbols(branchCatalogKey);
       database.addSymbolsToBranchBatch(branchCatalogKey, Array.from(allSymbolIds));
-      if (backfilledBlameMetadata) {
+      const vectorPath = path12.join(this.indexPath, "vectors");
+      const shouldFingerprintLegacyPair = !store.hasFingerprint() && existsSync7(vectorPath) && existsSync7(`${vectorPath}.meta.json`);
+      if (backfilledBlameMetadata || shouldFingerprintLegacyPair) {
         store.save();
       }
       if (scopedRoots) {
@@ -7672,7 +8589,6 @@ var Indexer = class {
         chunksProcessed: 0,
         totalChunks: 0
       });
-      this.releaseIndexingLock();
       return stats;
     }
     if (pendingChunks.length === 0) {
@@ -7681,7 +8597,7 @@ var Indexer = class {
       database.clearBranchSymbols(branchCatalogKey);
       database.addSymbolsToBranchBatch(branchCatalogKey, Array.from(allSymbolIds));
       store.save();
-      invertedIndex.save();
+      this.saveInvertedIndex(invertedIndex);
       if (scopedRoots) {
         this.replaceScopedFileHashCache(currentFileHashes, scopedRoots);
         this.clearScopedFailedBatches(scopedRoots);
@@ -7700,7 +8616,6 @@ var Indexer = class {
         chunksProcessed: 0,
         totalChunks: 0
       });
-      this.releaseIndexingLock();
       return stats;
     }
     onProgress?.({
@@ -7931,7 +8846,7 @@ var Indexer = class {
     database.clearBranchSymbols(branchCatalogKey);
     database.addSymbolsToBranchBatch(branchCatalogKey, Array.from(allSymbolIds));
     store.save();
-    invertedIndex.save();
+    this.saveInvertedIndex(invertedIndex);
     if (scopedRoots) {
       this.replaceScopedFileHashCache(currentFileHashes, scopedRoots);
     } else {
@@ -7983,7 +8898,6 @@ var Indexer = class {
       chunksProcessed: stats.indexedChunks,
       totalChunks: pendingChunks.length
     });
-    this.releaseIndexingLock();
     return stats;
   }
   async getQueryEmbedding(query, provider) {
@@ -8049,8 +8963,8 @@ var Indexer = class {
     return intersection / union;
   }
   async search(query, limit, options) {
-    const { store, provider, database } = await this.ensureInitialized();
-    const compatibility = this.checkCompatibility();
+    const { store, provider, invertedIndex, database, readIssues, compatibility } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "vectors", "database");
     if (!compatibility.compatible) {
       throw new Error(
         `${compatibility.reason ?? "Index is incompatible with current embedding provider."} A possible solution is to run index_codebase with force=true to rebuild the index.`
@@ -8064,6 +8978,7 @@ var Indexer = class {
     const maxResults = limit ?? this.config.search.maxResults;
     const hybridWeight = options?.hybridWeight ?? this.config.search.hybridWeight;
     const fusionStrategy = this.config.search.fusionStrategy;
+    const effectiveHybridWeight = fusionStrategy === "weighted" && readIssues.some((issue) => issue.component === "keyword") ? 0 : hybridWeight;
     const rrfK = this.config.search.rrfK;
     const rerankTopN = this.config.search.rerankTopN;
     const filterByBranch = options?.filterByBranch ?? true;
@@ -8072,7 +8987,7 @@ var Indexer = class {
     this.logger.search("debug", "Starting search", {
       query,
       maxResults,
-      hybridWeight,
+      hybridWeight: effectiveHybridWeight,
       fusionStrategy,
       rrfK,
       rerankTopN,
@@ -8080,13 +8995,22 @@ var Indexer = class {
     });
     const embeddingStartTime = performance2.now();
     const embeddingQuery = stripFilePathHint(query);
-    const embedding = await this.getQueryEmbedding(embeddingQuery, provider);
+    let embedding;
+    try {
+      embedding = await this.getQueryEmbedding(embeddingQuery, provider);
+    } catch (error) {
+      this.logger.warn("Query embedding failed; falling back to keyword-only search", {
+        query,
+        error: getErrorMessage2(error),
+        action: "Check the embedding provider configuration and retry search after restoring provider health."
+      });
+    }
     const embeddingMs = performance2.now() - embeddingStartTime;
     const vectorStartTime = performance2.now();
-    const semanticResults = store.search(embedding, maxResults * 4);
+    const semanticResults = embedding ? store.search(embedding, maxResults * 4) : [];
     const vectorMs = performance2.now() - vectorStartTime;
     const keywordStartTime = performance2.now();
-    const keywordResults = await this.keywordSearch(query, maxResults * 4);
+    const keywordResults = await this.keywordSearch(query, maxResults * 4, store, invertedIndex);
     const keywordMs = performance2.now() - keywordStartTime;
     let branchChunkIds = null;
     if (filterByBranch && (this.config.scope === "global" || this.currentBranch !== "default")) {
@@ -8118,12 +9042,13 @@ var Indexer = class {
       });
     }
     const fusionStartTime = performance2.now();
+    const rankingHybridWeight = embedding === void 0 && fusionStrategy === "weighted" ? 1 : effectiveHybridWeight;
     const combined = rankHybridResults(query, semanticCandidates, keywordCandidates, {
       fusionStrategy,
       rrfK,
       rerankTopN,
       limit: maxResults,
-      hybridWeight,
+      hybridWeight: rankingHybridWeight,
       prioritizeSourcePaths: sourceIntent
     });
     const rerankedCombined = await this.rerankCandidatesWithApi(query, combined, {
@@ -8223,8 +9148,7 @@ var Indexer = class {
       })
     );
   }
-  async keywordSearch(query, limit) {
-    const { store, invertedIndex } = await this.ensureInitialized();
+  async keywordSearch(query, limit, store, invertedIndex) {
     const scores = invertedIndex.search(query);
     if (scores.size === 0) {
       return [];
@@ -8242,24 +9166,54 @@ var Indexer = class {
     return results.slice(0, limit);
   }
   async getStatus() {
-    const { store, configuredProviderInfo, database } = await this.ensureInitialized();
+    const { store, configuredProviderInfo, database, readIssues, compatibility } = await this.ensureInitialized();
     const failedBatchesCount = this.getFailedBatchesCount();
+    const vectorCount = store.count();
+    const statusReadIssues = [...readIssues];
+    let startupWarning = "";
+    if (!statusReadIssues.some((issue) => issue.component === "database")) {
+      try {
+        startupWarning = database.getMetadata(STARTUP_WARNING_METADATA_KEY) ?? "";
+      } catch (error) {
+        const message = this.getDatabaseReadIssueMessage();
+        statusReadIssues.push(this.createReadIssue("database", message));
+        if (!this.readIssues.some((issue) => issue.component === "database")) {
+          this.recordReadIssue("database", message, error);
+        }
+      }
+    }
+    const readWarning = statusReadIssues.map((issue) => issue.message).join(" ");
+    const warning = [readWarning, startupWarning].filter((message) => message.length > 0).join(" ");
+    const hasBlockingReadIssue = statusReadIssues.some((issue) => issue.blocking);
     return {
-      indexed: store.count() > 0,
-      vectorCount: store.count(),
+      indexed: vectorCount > 0 && !hasBlockingReadIssue,
+      vectorCount,
       provider: configuredProviderInfo.provider,
       model: configuredProviderInfo.modelInfo.model,
       indexPath: this.indexPath,
       currentBranch: this.currentBranch,
       baseBranch: this.baseBranch,
-      compatibility: this.indexCompatibility,
+      compatibility,
       failedBatchesCount,
       failedBatchesPath: failedBatchesCount > 0 ? this.failedBatchesPath : void 0,
-      warning: database.getMetadata(STARTUP_WARNING_METADATA_KEY) ?? void 0
+      warning: warning || void 0
     };
   }
+  async forceIndex(onProgress) {
+    return this.withIndexMutationLease("force-index", async (recoveredOwners) => {
+      await this.ensureInitializedUnlocked(recoveredOwners);
+      await this.clearIndexUnlocked();
+      return this.indexUnlocked(onProgress, [], true);
+    });
+  }
   async clearIndex() {
-    const { store, invertedIndex, database } = await this.ensureInitialized();
+    await this.withIndexMutationLease("clear", async (recoveredOwners) => {
+      await this.ensureInitializedUnlocked(recoveredOwners);
+      await this.clearIndexUnlocked();
+    });
+  }
+  async clearIndexUnlocked() {
+    const { store, invertedIndex, database } = this.requireLoadedIndexState();
     if (this.config.scope === "global") {
       store.load();
       invertedIndex.load();
@@ -8286,7 +9240,7 @@ var Indexer = class {
         store.clear();
         store.save();
         invertedIndex.clear();
-        invertedIndex.save();
+        this.saveInvertedIndex(invertedIndex);
         this.fileHashCache.clear();
         this.saveFileHashCache();
         database.clearAllIndexedData();
@@ -8310,14 +9264,7 @@ var Indexer = class {
       this.indexCompatibility = compatibility;
       return;
     }
-    const localProjectIndexPaths = [path11.join(this.projectRoot, getHostProjectIndexRelativePath(this.host))];
-    if (this.host !== "opencode") {
-      localProjectIndexPaths.push(path11.join(this.projectRoot, getHostProjectIndexRelativePath("opencode")));
-    }
-    const isLocalProjectIndex = localProjectIndexPaths.some(
-      (localPath) => path11.resolve(this.indexPath) === path11.resolve(localPath)
-    );
-    if (!isLocalProjectIndex) {
+    if (!this.isLocalProjectIndexPath()) {
       throw new Error(
         "Project-scoped force rebuild is unsafe while using an inherited worktree index. Create a local project config boundary before clearing the index."
       );
@@ -8325,7 +9272,7 @@ var Indexer = class {
     store.clear();
     store.save();
     invertedIndex.clear();
-    invertedIndex.save();
+    this.saveInvertedIndex(invertedIndex);
     this.fileHashCache.clear();
     this.saveFileHashCache();
     database.clearAllIndexedData();
@@ -8343,7 +9290,13 @@ var Indexer = class {
     this.indexCompatibility = this.validateIndexCompatibility(this.configuredProviderInfo);
   }
   async healthCheck() {
-    const { store, invertedIndex, database } = await this.ensureInitialized();
+    return this.withIndexMutationLease("health-check", async (recoveredOwners) => {
+      await this.ensureInitializedUnlocked(recoveredOwners);
+      return this.healthCheckUnlocked();
+    });
+  }
+  async healthCheckUnlocked() {
+    const { store, invertedIndex, database } = this.requireLoadedIndexState();
     this.logger.gc("info", "Starting health check");
     const allMetadata = store.getAllMetadata();
     const filePathsToChunkKeys = /* @__PURE__ */ new Map();
@@ -8356,7 +9309,7 @@ var Indexer = class {
     const removedChunkKeys = [];
     const chunkKeysByRemovedFile = /* @__PURE__ */ new Map();
     for (const [filePath, chunkKeys] of filePathsToChunkKeys) {
-      if (!existsSync6(filePath)) {
+      if (!existsSync7(filePath)) {
         chunkKeysByRemovedFile.set(filePath, chunkKeys);
         for (const key of chunkKeys) {
           removedChunkKeys.push(key);
@@ -8381,7 +9334,7 @@ var Indexer = class {
     const removedCount = removedChunkKeys.length;
     if (removedCount > 0) {
       store.save();
-      invertedIndex.save();
+      this.saveInvertedIndex(invertedIndex);
     }
     let gcOrphanEmbeddings;
     let gcOrphanChunks;
@@ -8396,7 +9349,7 @@ var Indexer = class {
       if (!await this.tryResetCorruptedIndex("running index health check", error)) {
         throw error;
       }
-      await this.ensureInitialized();
+      await this.initializeUnlocked("writer", [], { skipAutoGc: true });
       return {
         removed: 0,
         filePaths: [],
@@ -8405,7 +9358,7 @@ var Indexer = class {
         gcOrphanSymbols: 0,
         gcOrphanCallEdges: 0,
         resetCorruptedIndex: true,
-        warning: this.getCorruptedIndexWarning(path11.join(this.indexPath, "codebase.db"))
+        warning: this.getCorruptedIndexWarning(path12.join(this.indexPath, "codebase.db"))
       };
     }
     this.logger.recordGc(removedCount, gcOrphanChunks, gcOrphanEmbeddings);
@@ -8418,7 +9371,13 @@ var Indexer = class {
     return { removed: removedCount, filePaths: removedFilePaths, gcOrphanEmbeddings, gcOrphanChunks, gcOrphanSymbols, gcOrphanCallEdges };
   }
   async retryFailedBatches() {
-    const { store, provider, invertedIndex, database, configuredProviderInfo } = await this.ensureInitialized();
+    return this.withIndexMutationLease("retry-failed-batches", async (recoveredOwners) => {
+      await this.ensureInitializedUnlocked(recoveredOwners);
+      return this.retryFailedBatchesUnlocked();
+    });
+  }
+  async retryFailedBatchesUnlocked() {
+    const { store, provider, invertedIndex, database, configuredProviderInfo } = this.requireLoadedIndexState();
     const maxChunkTokens = getSafeEmbeddingChunkTokenLimit(configuredProviderInfo);
     const providerRateLimits = this.getProviderRateLimits(configuredProviderInfo.provider);
     const roots = this.config.scope === "global" ? this.getScopedRoots() : null;
@@ -8582,7 +9541,7 @@ var Indexer = class {
     }
     if (succeeded > 0) {
       store.save();
-      invertedIndex.save();
+      this.saveInvertedIndex(invertedIndex);
     }
     if (roots && succeeded > 0 && persistedStillFailing.length === 0 && this.hasProjectForceReembedPending()) {
       database.deleteMetadata(this.getProjectForceReembedMetadataKey());
@@ -8610,15 +9569,16 @@ var Indexer = class {
     }
   }
   async getDatabaseStats() {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     return database.getStats();
   }
   getLogger() {
     return this.logger;
   }
   async findSimilar(code, limit = this.config.search.maxResults, options) {
-    const { store, provider, database } = await this.ensureInitialized();
-    const compatibility = this.checkCompatibility();
+    const { store, provider, database, readIssues, compatibility } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "vectors", "database");
     if (!compatibility.compatible) {
       throw new Error(
         `${compatibility.reason ?? "Index is incompatible with current embedding provider."} Run index_codebase with force=true to rebuild the index.`
@@ -8732,7 +9692,8 @@ var Indexer = class {
     );
   }
   async getCallers(targetName, callTypeFilter) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     const seen = /* @__PURE__ */ new Set();
     const results = [];
     for (const branchKey of this.getBranchCatalogKeys()) {
@@ -8746,7 +9707,8 @@ var Indexer = class {
     return results;
   }
   async getCallees(symbolId, callTypeFilter) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     const seen = /* @__PURE__ */ new Set();
     const results = [];
     for (const branchKey of this.getBranchCatalogKeys()) {
@@ -8760,43 +9722,50 @@ var Indexer = class {
     return results;
   }
   async findCallPath(fromName, toName, maxDepth) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     let shortest = [];
     for (const branchKey of this.getBranchCatalogKeys()) {
-      const path26 = database.findShortestPath(fromName, toName, branchKey, maxDepth);
-      if (path26.length > 0 && (shortest.length === 0 || path26.length < shortest.length)) {
-        shortest = path26;
+      const path27 = database.findShortestPath(fromName, toName, branchKey, maxDepth);
+      if (path27.length > 0 && (shortest.length === 0 || path27.length < shortest.length)) {
+        shortest = path27;
       }
     }
     return shortest;
   }
   async getSymbolsForBranch(branch) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     const resolvedBranch = branch ?? this.getBranchCatalogKey();
     return database.getSymbolsForBranch(resolvedBranch);
   }
   async getSymbolsForFiles(filePaths, branch) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     const resolvedBranch = branch ?? this.getBranchCatalogKey();
     return database.getSymbolsForFiles(filePaths, resolvedBranch);
   }
   async getTransitiveReachability(rootSymbolIds, direction, maxDepth) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     const branch = this.getBranchCatalogKey();
     return database.getTransitiveReachability(rootSymbolIds, branch, direction, maxDepth);
   }
   async detectCommunities(branch, symbolIds) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     const resolvedBranch = branch ?? this.getBranchCatalogKey();
     return database.detectCommunities(resolvedBranch, symbolIds);
   }
   async computeCentrality(branch) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     const resolvedBranch = branch ?? this.getBranchCatalogKey();
     return database.computeCentrality(resolvedBranch);
   }
   async getPrImpact(opts) {
-    const { database } = await this.ensureInitialized();
+    const { database, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "database");
     const execFileAsync3 = promisify3(execFile3);
     const changedFilesResult = await getChangedFiles({
       pr: opts.pr,
@@ -8819,7 +9788,7 @@ var Indexer = class {
         "Run index_codebase first to build the call graph and symbol index for this branch."
       );
     }
-    const absoluteChangedFiles = changedFiles.map((f) => path11.resolve(this.projectRoot, f));
+    const absoluteChangedFiles = changedFiles.map((f) => path12.resolve(this.projectRoot, f));
     const directSymbols = database.getSymbolsForFiles(absoluteChangedFiles, branchKey);
     const directIds = directSymbols.map((s) => s.id);
     const direction = opts.direction ?? "both";
@@ -8902,7 +9871,7 @@ var Indexer = class {
               projectRoot: this.projectRoot,
               baseBranch: this.baseBranch
             });
-            const otherAbsolute = otherChanged.files.map((f) => path11.resolve(this.projectRoot, f));
+            const otherAbsolute = otherChanged.files.map((f) => path12.resolve(this.projectRoot, f));
             const otherBranchKey = this.getBranchCatalogKeyFor(openPr.headRefName);
             const otherSymbols = database.getSymbolsForFiles(otherAbsolute, otherBranchKey);
             const otherLabels = /* @__PURE__ */ new Set();
@@ -8952,7 +9921,8 @@ var Indexer = class {
     };
   }
   async getVisualizationData(options) {
-    const { database, store } = await this.ensureInitialized();
+    const { database, store, readIssues } = await this.ensureInitialized();
+    this.requireReadableComponents(readIssues, "vectors", "database");
     const seenSymbols = /* @__PURE__ */ new Map();
     const seenEdges = /* @__PURE__ */ new Map();
     for (const branchKey of this.getBranchCatalogKeys()) {
@@ -8965,12 +9935,12 @@ var Indexer = class {
         if (meta.filePath) filePaths.add(meta.filePath);
       }
       const directory = options?.directory?.replace(/\/$/, "");
-      const absoluteDirectoryFilter = directory ? path11.resolve(this.projectRoot, directory) : void 0;
+      const absoluteDirectoryFilter = directory ? path12.resolve(this.projectRoot, directory) : void 0;
       for (const filePath of filePaths) {
         if (directory) {
-          const absoluteFilePath = path11.resolve(filePath);
+          const absoluteFilePath = path12.resolve(filePath);
           const matchesRelative = filePath === directory || filePath.startsWith(directory + "/");
-          const matchesProjectRelative = absoluteDirectoryFilter !== void 0 && (absoluteFilePath === absoluteDirectoryFilter || absoluteFilePath.startsWith(absoluteDirectoryFilter + path11.sep));
+          const matchesProjectRelative = absoluteDirectoryFilter !== void 0 && (absoluteFilePath === absoluteDirectoryFilter || absoluteFilePath.startsWith(absoluteDirectoryFilter + path12.sep));
           if (!matchesRelative && !matchesProjectRelative) {
             continue;
           }
@@ -8992,12 +9962,23 @@ var Indexer = class {
     return { symbols: [...seenSymbols.values()], edges: [...seenEdges.values()] };
   }
   async close() {
-    await this.database?.close();
+    this.database?.close();
+    for (const database of this.retiredDatabases) {
+      database.close();
+    }
+    this.retiredDatabases = [];
     this.database = null;
     this.store = null;
     this.invertedIndex = null;
     this.provider = null;
     this.reranker = null;
+    this.configuredProviderInfo = null;
+    this.indexCompatibility = null;
+    this.initializationMode = "none";
+    this.readIssues = [];
+    this.readerArtifactFingerprint = null;
+    this.writerArtifactFingerprint = null;
+    this.readerArtifactRetryAfter.clear();
   }
 };
 
@@ -9248,15 +10229,15 @@ function computeEvalMetrics(queries, perQuery, embeddingCallCount, embeddingToke
 }
 
 // src/eval/runner-config.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync7, rmSync, writeFileSync as writeFileSync3 } from "fs";
-import * as os4 from "os";
-import * as path13 from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync8, rmSync as rmSync2, writeFileSync as writeFileSync4 } from "fs";
+import * as os5 from "os";
+import * as path14 from "path";
 
 // src/config/rebase.ts
-import * as path12 from "path";
+import * as path13 from "path";
 function isWithinRoot(rootDir, targetPath) {
-  const relativePath = path12.relative(rootDir, targetPath);
-  return relativePath === "" || !relativePath.startsWith("..") && !path12.isAbsolute(relativePath);
+  const relativePath = path13.relative(rootDir, targetPath);
+  return relativePath === "" || !relativePath.startsWith("..") && !path13.isAbsolute(relativePath);
 }
 function rebasePathEntries(values, fromDir, toDir) {
   if (!Array.isArray(values)) {
@@ -9264,10 +10245,10 @@ function rebasePathEntries(values, fromDir, toDir) {
   }
   return values.filter((value) => typeof value === "string").map((value) => {
     const trimmed = value.trim();
-    if (!trimmed || path12.isAbsolute(trimmed)) {
+    if (!trimmed || path13.isAbsolute(trimmed)) {
       return trimmed;
     }
-    return normalizePathSeparators(path12.normalize(path12.relative(toDir, path12.resolve(fromDir, trimmed))));
+    return normalizePathSeparators(path13.normalize(path13.relative(toDir, path13.resolve(fromDir, trimmed))));
   }).filter(Boolean);
 }
 function resolveInheritedKnowledgeBaseEntries(values, sourceRoot, targetRoot) {
@@ -9279,17 +10260,17 @@ function resolveInheritedKnowledgeBaseEntries(values, sourceRoot, targetRoot) {
     if (!trimmed) {
       return trimmed;
     }
-    if (path12.isAbsolute(trimmed)) {
+    if (path13.isAbsolute(trimmed)) {
       if (isWithinRoot(sourceRoot, trimmed)) {
-        return normalizePathSeparators(path12.normalize(path12.relative(sourceRoot, trimmed) || "."));
+        return normalizePathSeparators(path13.normalize(path13.relative(sourceRoot, trimmed) || "."));
       }
-      return path12.normalize(trimmed);
+      return path13.normalize(trimmed);
     }
-    const resolvedFromSource = path12.resolve(sourceRoot, trimmed);
+    const resolvedFromSource = path13.resolve(sourceRoot, trimmed);
     if (isWithinRoot(sourceRoot, resolvedFromSource)) {
-      return normalizePathSeparators(path12.normalize(trimmed));
+      return normalizePathSeparators(path13.normalize(trimmed));
     }
-    return normalizePathSeparators(path12.normalize(path12.relative(targetRoot, resolvedFromSource)));
+    return normalizePathSeparators(path13.normalize(path13.relative(targetRoot, resolvedFromSource)));
   }).filter(Boolean);
 }
 
@@ -9327,7 +10308,7 @@ function validateEvalConfigShape(rawConfig, filePath) {
 }
 function parseJsonConfigFile(filePath) {
   try {
-    return validateEvalConfigShape(JSON.parse(readFileSync7(filePath, "utf-8")), filePath);
+    return validateEvalConfigShape(JSON.parse(readFileSync8(filePath, "utf-8")), filePath);
   } catch (error) {
     if (error instanceof Error && error.message.startsWith("Eval config at ")) {
       throw error;
@@ -9337,20 +10318,20 @@ function parseJsonConfigFile(filePath) {
   }
 }
 function toAbsolute(projectRoot, maybeRelative) {
-  return path13.isAbsolute(maybeRelative) ? maybeRelative : path13.join(projectRoot, maybeRelative);
+  return path14.isAbsolute(maybeRelative) ? maybeRelative : path14.join(projectRoot, maybeRelative);
 }
 function isProjectScopedConfigPath(configPath) {
-  return path13.basename(configPath) === "codebase-index.json" && path13.basename(path13.dirname(configPath)) === ".opencode";
+  return path14.basename(configPath) === "codebase-index.json" && path14.basename(path14.dirname(configPath)) === ".opencode";
 }
 function normalizeEvalConfigKnowledgeBases(rawConfig, projectRoot, resolvedConfigPath) {
   const config = rawConfig && typeof rawConfig === "object" ? { ...rawConfig } : {};
   const rebaseEntries = (values) => isProjectScopedConfigPath(resolvedConfigPath) ? resolveInheritedKnowledgeBaseEntries(
     values,
-    path13.dirname(path13.dirname(resolvedConfigPath)),
+    path14.dirname(path14.dirname(resolvedConfigPath)),
     projectRoot
   ) : rebasePathEntries(
     values,
-    path13.dirname(resolvedConfigPath),
+    path14.dirname(resolvedConfigPath),
     projectRoot
   );
   if (Array.isArray(config.knowledgeBases)) {
@@ -9363,7 +10344,7 @@ function normalizeEvalConfigKnowledgeBases(rawConfig, projectRoot, resolvedConfi
 }
 function loadRawConfig(projectRoot, configPath) {
   const fromPath = configPath ? toAbsolute(projectRoot, configPath) : null;
-  if (fromPath && existsSync7(fromPath)) {
+  if (fromPath && existsSync8(fromPath)) {
     return normalizeEvalConfigKnowledgeBases(
       parseJsonConfigFile(fromPath),
       projectRoot,
@@ -9371,15 +10352,15 @@ function loadRawConfig(projectRoot, configPath) {
     );
   }
   const projectConfig = resolveProjectConfigPath(projectRoot);
-  if (existsSync7(projectConfig)) {
+  if (existsSync8(projectConfig)) {
     return normalizeEvalConfigKnowledgeBases(
       parseJsonConfigFile(projectConfig),
       projectRoot,
       projectConfig
     );
   }
-  const globalConfig = path13.join(os4.homedir(), ".config", "opencode", "codebase-index.json");
-  if (existsSync7(globalConfig)) {
+  const globalConfig = path14.join(os5.homedir(), ".config", "opencode", "codebase-index.json");
+  if (existsSync8(globalConfig)) {
     return parseJsonConfigFile(globalConfig);
   }
   return {};
@@ -9388,24 +10369,24 @@ function getIndexRootPath(projectRoot, scope) {
   return scope === "global" ? getGlobalIndexPath() : resolveProjectIndexPath(projectRoot, scope);
 }
 function getLocalProjectIndexRoot(projectRoot) {
-  return path13.join(projectRoot, ".opencode", "index");
+  return path14.join(projectRoot, ".opencode", "index");
 }
 function getLocalProjectConfigPath(projectRoot) {
-  return path13.join(projectRoot, ".opencode", "codebase-index.json");
+  return path14.join(projectRoot, ".opencode", "codebase-index.json");
 }
 function clearIndexRoot(projectRoot, scope) {
   const indexRoot = scope === "global" ? getIndexRootPath(projectRoot, scope) : getLocalProjectIndexRoot(projectRoot);
-  if (existsSync7(indexRoot)) {
-    rmSync(indexRoot, { recursive: true, force: true });
+  if (existsSync8(indexRoot)) {
+    rmSync2(indexRoot, { recursive: true, force: true });
   }
 }
 function ensureLocalEvalProjectConfig(projectRoot, configPath) {
   const localConfigPath = getLocalProjectConfigPath(projectRoot);
   const resolvedConfigPath = configPath ? toAbsolute(projectRoot, configPath) : resolveProjectConfigPath(projectRoot);
-  if (!configPath && existsSync7(localConfigPath)) {
+  if (!configPath && existsSync8(localConfigPath)) {
     return localConfigPath;
   }
-  if (!existsSync7(resolvedConfigPath) || resolvedConfigPath === localConfigPath) {
+  if (!existsSync8(resolvedConfigPath) || resolvedConfigPath === localConfigPath) {
     return resolvedConfigPath;
   }
   const sourceConfig = normalizeEvalConfigKnowledgeBases(
@@ -9413,8 +10394,8 @@ function ensureLocalEvalProjectConfig(projectRoot, configPath) {
     projectRoot,
     resolvedConfigPath
   );
-  mkdirSync3(path13.dirname(localConfigPath), { recursive: true });
-  writeFileSync3(localConfigPath, JSON.stringify(sourceConfig, null, 2), "utf-8");
+  mkdirSync4(path14.dirname(localConfigPath), { recursive: true });
+  writeFileSync4(localConfigPath, JSON.stringify(sourceConfig, null, 2), "utf-8");
   return localConfigPath;
 }
 function loadParsedConfig(projectRoot, configPath) {
@@ -9447,9 +10428,9 @@ function getEmbeddingCostPer1MTokens(embeddingProvider) {
 }
 
 // src/eval/schema.ts
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 function parseJsonFile(filePath) {
-  const content = readFileSync8(filePath, "utf-8");
+  const content = readFileSync9(filePath, "utf-8");
   try {
     return JSON.parse(content);
   } catch (error) {
@@ -9463,23 +10444,23 @@ function isRecord2(value) {
 function isStringArray3(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
-function asPositiveNumber(value, path26) {
+function asPositiveNumber(value, path27) {
   if (typeof value !== "number" || Number.isNaN(value) || value < 0) {
-    throw new Error(`${path26} must be a non-negative number`);
+    throw new Error(`${path27} must be a non-negative number`);
   }
   return value;
 }
-function parseQueryType(value, path26) {
+function parseQueryType(value, path27) {
   if (value === "definition" || value === "implementation-intent" || value === "similarity" || value === "keyword-heavy") {
     return value;
   }
   throw new Error(
-    `${path26} must be one of: definition, implementation-intent, similarity, keyword-heavy`
+    `${path27} must be one of: definition, implementation-intent, similarity, keyword-heavy`
   );
 }
-function parseExpected(input, path26) {
+function parseExpected(input, path27) {
   if (!isRecord2(input)) {
-    throw new Error(`${path26} must be an object`);
+    throw new Error(`${path27} must be an object`);
   }
   const filePathRaw = input.filePath;
   const acceptableFilesRaw = input.acceptableFiles;
@@ -9488,16 +10469,16 @@ function parseExpected(input, path26) {
   const filePath = typeof filePathRaw === "string" ? filePathRaw : void 0;
   const acceptableFiles = isStringArray3(acceptableFilesRaw) ? acceptableFilesRaw : void 0;
   if (!filePath && (!acceptableFiles || acceptableFiles.length === 0)) {
-    throw new Error(`${path26} must include either expected.filePath or expected.acceptableFiles`);
+    throw new Error(`${path27} must include either expected.filePath or expected.acceptableFiles`);
   }
   if (acceptableFilesRaw !== void 0 && !isStringArray3(acceptableFilesRaw)) {
-    throw new Error(`${path26}.acceptableFiles must be an array of strings`);
+    throw new Error(`${path27}.acceptableFiles must be an array of strings`);
   }
   if (symbolRaw !== void 0 && typeof symbolRaw !== "string") {
-    throw new Error(`${path26}.symbol must be a string when provided`);
+    throw new Error(`${path27}.symbol must be a string when provided`);
   }
   if (branchRaw !== void 0 && typeof branchRaw !== "string") {
-    throw new Error(`${path26}.branch must be a string when provided`);
+    throw new Error(`${path27}.branch must be a string when provided`);
   }
   return {
     filePath,
@@ -9507,25 +10488,25 @@ function parseExpected(input, path26) {
   };
 }
 function parseQuery(input, index) {
-  const path26 = `queries[${index}]`;
+  const path27 = `queries[${index}]`;
   if (!isRecord2(input)) {
-    throw new Error(`${path26} must be an object`);
+    throw new Error(`${path27} must be an object`);
   }
   const id = input.id;
   const query = input.query;
   const queryType = input.queryType;
   const expected = input.expected;
   if (typeof id !== "string" || id.trim().length === 0) {
-    throw new Error(`${path26}.id must be a non-empty string`);
+    throw new Error(`${path27}.id must be a non-empty string`);
   }
   if (typeof query !== "string" || query.trim().length === 0) {
-    throw new Error(`${path26}.query must be a non-empty string`);
+    throw new Error(`${path27}.query must be a non-empty string`);
   }
   return {
     id,
     query,
-    queryType: parseQueryType(queryType, `${path26}.queryType`),
-    expected: parseExpected(expected, `${path26}.expected`)
+    queryType: parseQueryType(queryType, `${path27}.queryType`),
+    expected: parseExpected(expected, `${path27}.expected`)
   };
 }
 function parseGoldenDataset(raw, sourceLabel) {
@@ -9708,13 +10689,13 @@ async function runEvaluation(options) {
     };
     const outputDir = createRunDirectory(toAbsolute(options.projectRoot, options.outputRoot));
     const perQueryArtifact = buildPerQueryArtifact(perQuery);
-    writeJson(path14.join(outputDir, "summary.json"), summary);
-    writeJson(path14.join(outputDir, "per-query.json"), perQueryArtifact);
+    writeJson(path15.join(outputDir, "summary.json"), summary);
+    writeJson(path15.join(outputDir, "per-query.json"), perQueryArtifact);
     let comparison;
     if (againstPath) {
       const baseline = loadSummary(againstPath);
       comparison = compareSummaries(summary, baseline, againstPath);
-      writeJson(path14.join(outputDir, "compare.json"), comparison);
+      writeJson(path15.join(outputDir, "compare.json"), comparison);
     }
     let gate;
     if (options.ciMode) {
@@ -9724,10 +10705,10 @@ async function runEvaluation(options) {
       const budget = loadBudget(budgetPath);
       if (!comparison && budget.baselinePath) {
         const resolvedBaseline = toAbsolute(options.projectRoot, budget.baselinePath);
-        if (existsSync8(resolvedBaseline)) {
+        if (existsSync9(resolvedBaseline)) {
           const baselineSummary = loadSummary(resolvedBaseline);
           comparison = compareSummaries(summary, baselineSummary, resolvedBaseline);
-          writeJson(path14.join(outputDir, "compare.json"), comparison);
+          writeJson(path15.join(outputDir, "compare.json"), comparison);
         } else if (budget.failOnMissingBaseline) {
           throw new Error(
             `Budget baseline is missing: ${resolvedBaseline}. Set failOnMissingBaseline=false to allow CI run without baseline.`
@@ -9737,7 +10718,7 @@ async function runEvaluation(options) {
       gate = evaluateBudgetGate(budget, summary, comparison);
     }
     const markdown = createSummaryMarkdown(summary, comparison, gate);
-    writeText(path14.join(outputDir, "summary.md"), markdown);
+    writeText(path15.join(outputDir, "summary.md"), markdown);
     return { outputDir, summary, perQuery, comparison, gate };
   } finally {
     await indexer.close();
@@ -9795,23 +10776,23 @@ async function runSweep(options, sweep) {
     bestByMrrAt10,
     bestByP95Latency
   };
-  writeJson(path14.join(outputDir, "compare.json"), aggregate);
+  writeJson(path15.join(outputDir, "compare.json"), aggregate);
   const md = createSummaryMarkdown(
     bestByHitAt5?.summary ?? runs[0].summary,
     bestByHitAt5?.comparison,
     void 0,
     aggregate
   );
-  writeText(path14.join(outputDir, "summary.md"), md);
-  writeJson(path14.join(outputDir, "summary.json"), bestByHitAt5?.summary ?? runs[0].summary);
+  writeText(path15.join(outputDir, "summary.md"), md);
+  writeJson(path15.join(outputDir, "summary.json"), bestByHitAt5?.summary ?? runs[0].summary);
   return { outputDir, aggregate };
 }
 
 // src/eval/cli.ts
-import * as path16 from "path";
+import * as path17 from "path";
 
 // src/eval/cli-parser.ts
-import * as path15 from "path";
+import * as path16 from "path";
 function printUsage() {
   console.log(`
 Usage:
@@ -9883,12 +10864,12 @@ function parseEvalArgs(argv, cwd) {
     const arg = argv[i];
     const next = argv[i + 1];
     if (arg === "--project" && next) {
-      parsed.projectRoot = path15.resolve(cwd, next);
+      parsed.projectRoot = path16.resolve(cwd, next);
       i += 1;
       continue;
     }
     if (arg === "--config" && next) {
-      parsed.configPath = path15.resolve(cwd, next);
+      parsed.configPath = path16.resolve(cwd, next);
       i += 1;
       continue;
     }
@@ -10084,22 +11065,22 @@ async function handleEvalCommand(args, cwd) {
     if (!parsed.againstPath.endsWith(".json")) {
       throw new Error("eval diff --against must point to a summary JSON file");
     }
-    const currentSummary = loadSummary(path16.resolve(parsed.projectRoot, currentPath), {
+    const currentSummary = loadSummary(path17.resolve(parsed.projectRoot, currentPath), {
       allowLegacyDiversityMetrics: true
     });
-    const baselineSummary = loadSummary(path16.resolve(parsed.projectRoot, parsed.againstPath), {
+    const baselineSummary = loadSummary(path17.resolve(parsed.projectRoot, parsed.againstPath), {
       allowLegacyDiversityMetrics: true
     });
     const comparison = compareSummaries(
       currentSummary,
       baselineSummary,
-      path16.resolve(parsed.projectRoot, parsed.againstPath)
+      path17.resolve(parsed.projectRoot, parsed.againstPath)
     );
-    const outputDir = createRunDirectory(path16.resolve(parsed.projectRoot, parsed.outputRoot));
+    const outputDir = createRunDirectory(path17.resolve(parsed.projectRoot, parsed.outputRoot));
     const summaryMd = createSummaryMarkdown(currentSummary, comparison);
-    writeJson(path16.join(outputDir, "compare.json"), comparison);
-    writeText(path16.join(outputDir, "summary.md"), summaryMd);
-    writeJson(path16.join(outputDir, "summary.json"), currentSummary);
+    writeJson(path17.join(outputDir, "compare.json"), comparison);
+    writeText(path17.join(outputDir, "summary.md"), summaryMd);
+    writeJson(path17.join(outputDir, "summary.json"), currentSummary);
     console.log(`Eval diff complete. Artifacts: ${outputDir}`);
     return 0;
   }
@@ -10108,7 +11089,7 @@ async function handleEvalCommand(args, cwd) {
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { readFileSync as readFileSync10 } from "fs";
+import { readFileSync as readFileSync11 } from "fs";
 
 // src/mcp-server/register-prompts.ts
 import { z } from "zod";
@@ -10299,6 +11280,10 @@ function formatStatus(status) {
       lines.push(`Failed batches: ${status.failedBatchesPath}`);
     }
   }
+  if (status.warning) {
+    lines.push("");
+    lines.push(`INDEX WARNING: ${status.warning}`);
+  }
   if (status.compatibility && !status.compatibility.compatible) {
     lines.push("");
     lines.push(`COMPATIBILITY WARNING: ${status.compatibility.reason}`);
@@ -10404,16 +11389,16 @@ function formatCallGraphCallees(symbolId, callees, relationshipType) {
     return `[${index + 1}] \u2192 ${edge.targetName} (${edge.callType})${confidence} at line ${edge.line}${edge.isResolved ? ` [resolved: ${edge.toSymbolId}]` : " [unresolved]"}`;
   }).join("\n");
 }
-function formatCallGraphPath(from, to, path26) {
-  if (path26.length === 0) {
+function formatCallGraphPath(from, to, path27) {
+  if (path27.length === 0) {
     return `No path found between "${from}" and "${to}". They may be in disconnected components, or the call graph index needs updating.`;
   }
-  const formatted = path26.map((hop, index) => {
+  const formatted = path27.map((hop, index) => {
     const prefix = index === 0 ? "[start]" : `--${hop.callType}-->`;
     const location = hop.filePath ? ` (${hop.filePath}:${hop.line})` : "";
     return `${prefix} ${hop.symbolName}${location}`;
   });
-  return `Path (${path26.length} hops):
+  return `Path (${path27.length} hops):
 ${formatted.join("\n")}`;
 }
 function formatResultHeader(result, index) {
@@ -10504,12 +11489,12 @@ function formatPrImpact(result) {
 }
 
 // src/tools/operations.ts
-import { existsSync as existsSync11, realpathSync, statSync as statSync3 } from "fs";
-import * as path20 from "path";
+import { existsSync as existsSync12, realpathSync as realpathSync2, statSync as statSync4 } from "fs";
+import * as path21 from "path";
 
 // src/config/merger.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
-import * as path17 from "path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync5, readFileSync as readFileSync10, writeFileSync as writeFileSync5 } from "fs";
+import * as path18 from "path";
 var PROJECT_OVERRIDE_KEYS = [
   "embeddingProvider",
   "customProvider",
@@ -10542,8 +11527,8 @@ function mergeUniqueStringArray(values) {
   return [...new Set(values.map((value) => String(value).trim()))];
 }
 function normalizeKnowledgeBasePath(value) {
-  let normalized = path17.normalize(String(value).trim());
-  const root = path17.parse(normalized).root;
+  let normalized = path18.normalize(String(value).trim());
+  const root = path18.parse(normalized).root;
   while (normalized.length > root.length && /[\\/]$/.test(normalized)) {
     normalized = normalized.slice(0, -1);
   }
@@ -10577,11 +11562,11 @@ function validateConfigLayerShape(rawConfig, filePath) {
   return rawConfig;
 }
 function loadJsonFile(filePath) {
-  if (!existsSync9(filePath)) {
+  if (!existsSync10(filePath)) {
     return null;
   }
   try {
-    const content = readFileSync9(filePath, "utf-8");
+    const content = readFileSync10(filePath, "utf-8");
     return validateConfigLayerShape(JSON.parse(content), filePath);
   } catch (error) {
     if (error instanceof Error && error.message.startsWith("Config file ")) {
@@ -10596,8 +11581,8 @@ function loadConfigFile(filePath) {
 }
 function materializeLocalProjectConfig(projectRoot, config, host = "opencode") {
   const localConfigPath = resolveWritableProjectConfigPath(projectRoot, host);
-  mkdirSync4(path17.dirname(localConfigPath), { recursive: true });
-  writeFileSync4(localConfigPath, JSON.stringify(config, null, 2), "utf-8");
+  mkdirSync5(path18.dirname(localConfigPath), { recursive: true });
+  writeFileSync5(localConfigPath, JSON.stringify(config, null, 2), "utf-8");
   return localConfigPath;
 }
 function loadProjectConfigLayer(projectRoot, host = "opencode") {
@@ -10607,7 +11592,7 @@ function loadProjectConfigLayer(projectRoot, host = "opencode") {
     return {};
   }
   const normalizedConfig = { ...projectConfig };
-  const projectConfigBaseDir = path17.dirname(path17.dirname(projectConfigPath));
+  const projectConfigBaseDir = path18.dirname(path18.dirname(projectConfigPath));
   if (Array.isArray(normalizedConfig.knowledgeBases)) {
     normalizedConfig.knowledgeBases = resolveInheritedKnowledgeBaseEntries(
       normalizedConfig.knowledgeBases,
@@ -10671,19 +11656,19 @@ function loadMergedConfig(projectRoot, host = "opencode") {
 }
 
 // src/tools/knowledge-base-paths.ts
-import * as path18 from "path";
+import * as path19 from "path";
 function resolveConfigPathValue(value, baseDir) {
   const trimmed = value.trim();
   if (!trimmed) {
     return trimmed;
   }
-  const absolutePath = path18.isAbsolute(trimmed) ? trimmed : path18.resolve(baseDir, trimmed);
-  return path18.normalize(absolutePath);
+  const absolutePath = path19.isAbsolute(trimmed) ? trimmed : path19.resolve(baseDir, trimmed);
+  return path19.normalize(absolutePath);
 }
 
 // src/tools/config-state.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "fs";
-import * as path19 from "path";
+import { existsSync as existsSync11, mkdirSync as mkdirSync6, writeFileSync as writeFileSync6 } from "fs";
+import * as path20 from "path";
 function normalizeKnowledgeBasePaths(config, projectRoot) {
   const normalized = { ...config };
   if (Array.isArray(normalized.knowledgeBases)) {
@@ -10707,6 +11692,24 @@ function loadRuntimeConfig(projectRoot, host = "opencode") {
 var indexerCache = /* @__PURE__ */ new Map();
 var configCache = /* @__PURE__ */ new Map();
 var defaultProjectRoots = /* @__PURE__ */ new Map();
+function getIndexBusyResult(error) {
+  if (!isIndexLockContentionError(error)) return null;
+  const owner = error.owner;
+  const ownerText = owner ? `PID ${owner.pid}, operation ${owner.operation}, since ${owner.startedAt}` : "unreadable owner";
+  if (error.reason === "legacy-lock") {
+    return {
+      kind: "busy",
+      text: `INDEX_BUSY: legacy lock format detected (${ownerText}). Verify the PID and remove this lock manually only if it is stale.`
+    };
+  }
+  if (error.reason === "unknown-owner") {
+    return {
+      kind: "busy",
+      text: `INDEX_BUSY: unreadable or remote lock owner (${ownerText}). Automatic recovery was refused; manual verification is required.`
+    };
+  }
+  return { kind: "busy", text: `INDEX_BUSY: another index operation is already in progress (${ownerText}).` };
+}
 function getProjectRoot(projectRoot, host) {
   if (projectRoot) {
     return projectRoot;
@@ -10751,8 +11754,8 @@ function refreshIndexerForDirectory(projectRoot, host = "opencode", config = par
 }
 function shouldForceLocalizeProjectIndex(projectRoot, host = "opencode") {
   const root = getProjectRoot(projectRoot, host);
-  const localIndexPath = path20.join(root, getHostProjectIndexRelativePath(host));
-  if (existsSync11(localIndexPath)) {
+  const localIndexPath = path21.join(root, getHostProjectIndexRelativePath(host));
+  if (existsSync12(localIndexPath)) {
     return false;
   }
   const inheritedIndexPath = resolveWorktreeFallbackProjectIndexPath(root, host);
@@ -10808,35 +11811,46 @@ async function getCallGraphPath(projectRoot, host, from, to, maxDepth) {
 async function runIndexCodebase(projectRoot, host, args, onProgress) {
   const root = getProjectRoot(projectRoot, host);
   const key = getIndexerCacheKey(root, host);
-  const cachedConfig = configCache.get(key);
   let indexer = getIndexerForProject(root, host);
-  if (args.estimateOnly) {
-    return { kind: "estimate", estimate: await indexer.estimateCost() };
-  }
-  if (args.force) {
-    if (shouldForceLocalizeProjectIndex(root, host)) {
-      materializeLocalProjectConfig(root, loadProjectConfigLayer(root, host), host);
-      refreshIndexerForDirectory(root, host, cachedConfig);
-      indexer = getIndexerForProject(root, host);
-    }
-    await indexer.clearIndex();
-    refreshIndexerForDirectory(root, host, cachedConfig);
-    indexer = getIndexerForProject(root, host);
-  }
-  const stats = await indexer.index((progress) => {
-    if (onProgress) {
-      return onProgress(formatProgressTitle(progress), {
-        phase: progress.phase,
-        filesProcessed: progress.filesProcessed,
-        totalFiles: progress.totalFiles,
-        chunksProcessed: progress.chunksProcessed,
-        totalChunks: progress.totalChunks,
-        percentage: calculatePercentage(progress)
+  const runtimeConfig = configCache.get(key);
+  try {
+    if (args.estimateOnly) {
+      return { kind: "estimate", estimate: await indexer.estimateCost() };
+    }
+    const runIndex = async (target) => {
+      const operation = args.force ? target.forceIndex.bind(target) : target.index.bind(target);
+      return operation((progress) => {
+        if (onProgress) {
+          return onProgress(formatProgressTitle(progress), {
+            phase: progress.phase,
+            filesProcessed: progress.filesProcessed,
+            totalFiles: progress.totalFiles,
+            chunksProcessed: progress.chunksProcessed,
+            totalChunks: progress.totalChunks,
+            percentage: calculatePercentage(progress)
+          });
+        }
+        return Promise.resolve();
       });
+    };
+    let stats;
+    if (args.force && shouldForceLocalizeProjectIndex(root, host)) {
+      const inheritedIndexPath = resolveProjectIndexPath(root, runtimeConfig.scope, host);
+      stats = await withIndexLock(inheritedIndexPath, "force-index", async () => {
+        materializeLocalProjectConfig(root, loadProjectConfigLayer(root, host), host);
+        refreshIndexerForDirectory(root, host, runtimeConfig);
+        indexer = getIndexerForProject(root, host);
+        return runIndex(indexer);
+      }, { completeRecoveries: false });
+    } else {
+      stats = await runIndex(indexer);
     }
-    return Promise.resolve();
-  });
-  return { kind: "stats", stats };
+    return { kind: "stats", stats };
+  } catch (error) {
+    const busyResult = getIndexBusyResult(error);
+    if (!busyResult) throw error;
+    return busyResult;
+  }
 }
 async function getIndexStatus(projectRoot, host) {
   const indexer = getIndexerForProject(projectRoot, host);
@@ -10846,6 +11860,15 @@ async function getIndexHealthCheck(projectRoot, host) {
   const indexer = getIndexerForProject(projectRoot, host);
   return indexer.healthCheck();
 }
+async function runIndexHealthCheck(projectRoot, host) {
+  try {
+    return { kind: "health", health: await getIndexHealthCheck(projectRoot, host) };
+  } catch (error) {
+    const busyResult = getIndexBusyResult(error);
+    if (!busyResult) throw error;
+    return busyResult;
+  }
+}
 async function getPrImpact(projectRoot, host, params) {
   const indexer = getIndexerForProject(projectRoot, host);
   return indexer.getPrImpact({
@@ -10926,20 +11949,87 @@ var CHUNK_TYPE_ENUM = [
 ];
 
 // src/mcp-server/register-tools.ts
+function allowNullAsUndefined(schema) {
+  return z2.preprocess((value) => value === null ? void 0 : value, schema);
+}
 function registerMcpTools(server, runtime) {
+  server.tool(
+    "codebase_context",
+    "PREFERRED FIRST TOOL for any question about this repository. Use before built-in code search, grep, shell search, or broad file reads. Provide from+to for a dependency path, symbol for a definition, or only query for low-token conceptual discovery. Use call_graph directly for callers or callees.",
+    {
+      query: z2.string().describe("The codebase question or behavior to locate. Always provide the user's repository question here."),
+      from: allowNullAsUndefined(z2.string().optional()).describe("Source symbol. For dependency-path questions, extract the first endpoint and provide it here."),
+      to: allowNullAsUndefined(z2.string().optional()).describe("Target symbol. For dependency-path questions, extract the second endpoint and provide it here."),
+      symbol: allowNullAsUndefined(z2.string().optional()).describe("Exact symbol for an authoritative definition lookup. Omit when from and to are supplied."),
+      limit: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum number of search or definition results"),
+      maxDepth: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum call-graph traversal depth for from/to path lookup"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')")
+    },
+    async (args) => {
+      if (args.from && args.to) {
+        const path27 = await getCallGraphPath(runtime.projectRoot, runtime.host, args.from, args.to, args.maxDepth);
+        if (path27.length > 0) {
+          return { content: [{ type: "text", text: formatCallGraphPath(args.from, args.to, path27) }] };
+        }
+        const { callers } = await getCallGraphData(runtime.projectRoot, runtime.host, {
+          name: args.to,
+          direction: "callers"
+        });
+        const directEdge = callers.find((edge) => edge.fromSymbolName === args.from);
+        if (directEdge) {
+          const location = directEdge.fromSymbolFilePath ? ` at ${directEdge.fromSymbolFilePath}:${directEdge.line}` : "";
+          return {
+            content: [{
+              type: "text",
+              text: `Direct path: ${args.from} --${directEdge.callType}--> ${args.to}${location} (edge is ${directEdge.isResolved ? "resolved" : "unresolved"}).`
+            }]
+          };
+        }
+        return { content: [{ type: "text", text: formatCallGraphPath(args.from, args.to, path27) }] };
+      }
+      if (args.symbol) {
+        const results2 = await implementationLookup(runtime.projectRoot, runtime.host, args.symbol, {
+          limit: args.limit ?? 10,
+          fileType: args.fileType,
+          directory: args.directory
+        });
+        return { content: [{ type: "text", text: formatDefinitionLookup(results2, args.symbol) }] };
+      }
+      const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
+        limit: args.limit ?? 10,
+        fileType: args.fileType,
+        directory: args.directory,
+        metadataOnly: true
+      });
+      if (results.length === 0) {
+        return { content: [{ type: "text", text: "No matching code found. Try a different query or run index_codebase first." }] };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: `Found ${results.length} locations for "${args.query}":
+
+${formatCodebasePeek(results)}
+
+Use implementation_lookup for an authoritative definition, or call call_graph/call_graph_path once you have a symbol.`
+        }]
+      };
+    }
+  );
   server.tool(
     "codebase_search",
-    "Search codebase by MEANING, not keywords. Returns full code content. For just finding WHERE code is (saves ~90% tokens), use codebase_peek instead.",
+    "FULL-CONTENT semantic retrieval. Use after codebase_peek when you need implementation text, not as the default first step. For exact identifiers or exhaustive matches use grep instead.",
     {
       query: z2.string().describe("Natural language description of what code you're looking for. Describe behavior, not syntax."),
-      limit: z2.number().optional().default(5).describe("Maximum number of results to return"),
-      fileType: z2.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: z2.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: z2.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      contextLines: z2.number().optional().describe("Number of extra lines to include before/after each match (default: 0)"),
-      blameAuthor: z2.string().optional().describe("Filter by git blame author name or email"),
-      blameSha: z2.string().optional().describe("Filter by git blame commit SHA or prefix"),
-      blameSince: z2.string().optional().describe("Filter to chunks last changed on or after this date")
+      limit: allowNullAsUndefined(z2.number().optional().default(5)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(z2.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      contextLines: allowNullAsUndefined(z2.number().optional()).describe("Number of extra lines to include before/after each match (default: 0)"),
+      blameAuthor: allowNullAsUndefined(z2.string().optional()).describe("Filter by git blame author name or email"),
+      blameSha: allowNullAsUndefined(z2.string().optional()).describe("Filter by git blame commit SHA or prefix"),
+      blameSince: allowNullAsUndefined(z2.string().optional()).describe("Filter to chunks last changed on or after this date")
     },
     async (args) => {
       const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
@@ -10962,16 +12052,16 @@ ${formatSearchResults(results, "score")}` }] };
   );
   server.tool(
     "codebase_peek",
-    "Quick lookup of code locations by meaning. Returns only metadata (file, line, name, type) WITHOUT code content. Saves ~90% tokens vs codebase_search.",
+    "DIRECT LOW-TOKEN semantic location lookup for unfamiliar-code discovery. Prefer codebase_context when the request may involve definitions or graph navigation; use this specialized tool when you only need conceptual locations.",
     {
       query: z2.string().describe("Natural language description of what code you're looking for."),
-      limit: z2.number().optional().default(10).describe("Maximum number of results to return"),
-      fileType: z2.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: z2.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: z2.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      blameAuthor: z2.string().optional().describe("Filter by git blame author name or email"),
-      blameSha: z2.string().optional().describe("Filter by git blame commit SHA or prefix"),
-      blameSince: z2.string().optional().describe("Filter to chunks last changed on or after this date")
+      limit: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(z2.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      blameAuthor: allowNullAsUndefined(z2.string().optional()).describe("Filter by git blame author name or email"),
+      blameSha: allowNullAsUndefined(z2.string().optional()).describe("Filter by git blame commit SHA or prefix"),
+      blameSince: allowNullAsUndefined(z2.string().optional()).describe("Filter to chunks last changed on or after this date")
     },
     async (args) => {
       const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
@@ -10996,21 +12086,26 @@ Use Read tool to examine specific files.` }] };
   );
   server.tool(
     "index_codebase",
-    "Index the codebase for semantic search. Creates vector embeddings of code chunks. Incremental - only re-indexes changed files. Run before first codebase_search.",
+    "Create or refresh the semantic index. Call index_status first when readiness is unknown, then use this tool only if the index is missing, stale, or incompatible. Incremental by default; force=true rebuilds everything.",
     {
-      force: z2.boolean().optional().default(false).describe("Force reindex even if already indexed"),
-      estimateOnly: z2.boolean().optional().default(false).describe("Only show cost estimate without indexing"),
-      verbose: z2.boolean().optional().default(false).describe("Show detailed info about skipped files and parsing failures")
+      force: allowNullAsUndefined(z2.boolean().optional().default(false)).describe("Force reindex even if already indexed"),
+      estimateOnly: allowNullAsUndefined(z2.boolean().optional().default(false)).describe("Only show cost estimate without indexing"),
+      verbose: allowNullAsUndefined(z2.boolean().optional().default(false)).describe("Show detailed info about skipped files and parsing failures")
     },
     async (args) => {
       const result = await runIndexCodebase(runtime.projectRoot, runtime.host, args);
-      const text = result.kind === "estimate" ? formatCostEstimate(result.estimate) : formatIndexStats(result.stats, args.verbose ?? false);
-      return { content: [{ type: "text", text }] };
+      if (result.kind === "estimate") {
+        return { content: [{ type: "text", text: formatCostEstimate(result.estimate) }] };
+      }
+      if (result.kind === "busy") {
+        return { content: [{ type: "text", text: result.text }], isError: true };
+      }
+      return { content: [{ type: "text", text: formatIndexStats(result.stats, args.verbose ?? false) }] };
     }
   );
   server.tool(
     "index_status",
-    "Check the status of the codebase index. Shows whether the codebase is indexed, how many chunks are stored, and the embedding provider being used.",
+    "START HERE once per repository task when index readiness or freshness is unknown. Reports whether semantic retrieval is ready, chunk counts, compatibility, and the embedding provider. If ready, continue with codebase_peek or implementation_lookup; otherwise run index_codebase.",
     {},
     async () => {
       const status = await getIndexStatus(runtime.projectRoot, runtime.host);
@@ -11022,8 +12117,11 @@ Use Read tool to examine specific files.` }] };
     "Check index health and remove stale entries from deleted files. Run this to clean up the index after files have been deleted.",
     {},
     async () => {
-      const result = await getIndexHealthCheck(runtime.projectRoot, runtime.host);
-      return { content: [{ type: "text", text: formatHealthCheck(result) }] };
+      const result = await runIndexHealthCheck(runtime.projectRoot, runtime.host);
+      if (result.kind === "busy") {
+        return { content: [{ type: "text", text: result.text }], isError: true };
+      }
+      return { content: [{ type: "text", text: formatHealthCheck(result.health) }] };
     }
   );
   server.tool(
@@ -11039,9 +12137,13 @@ Use Read tool to examine specific files.` }] };
     "index_logs",
     "Get recent debug logs from the codebase indexer. Requires debug.enabled=true in config.",
     {
-      limit: z2.number().optional().default(20).describe("Maximum number of log entries to return"),
-      category: z2.enum(["search", "embedding", "cache", "gc", "branch", "general"]).optional().describe("Filter by log category"),
-      level: z2.enum(["error", "warn", "info", "debug"]).optional().describe("Filter by minimum log level")
+      limit: allowNullAsUndefined(z2.number().optional().default(20)).describe("Maximum number of log entries to return"),
+      category: allowNullAsUndefined(
+        z2.enum(["search", "embedding", "cache", "gc", "branch", "general"]).optional()
+      ).describe("Filter by log category"),
+      level: allowNullAsUndefined(
+        z2.enum(["error", "warn", "info", "debug"]).optional()
+      ).describe("Filter by minimum log level")
     },
     async (args) => {
       const result = await getIndexLogs(runtime.projectRoot, runtime.host, args);
@@ -11050,14 +12152,14 @@ Use Read tool to examine specific files.` }] };
   );
   server.tool(
     "find_similar",
-    "Find code similar to a given snippet. Use for duplicate detection, pattern discovery, or refactoring prep.",
+    "Use when you already have a code snippet and need analogous implementations, duplicates, patterns, or refactoring candidates. For a natural-language concept without example code, start with codebase_peek instead.",
     {
       code: z2.string().describe("The code snippet to find similar code for"),
-      limit: z2.number().optional().default(10).describe("Maximum number of results to return"),
-      fileType: z2.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: z2.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: z2.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      excludeFile: z2.string().optional().describe("Exclude results from this file path")
+      limit: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(z2.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      excludeFile: allowNullAsUndefined(z2.string().optional()).describe("Exclude results from this file path")
     },
     async (args) => {
       const results = await findSimilarCode(runtime.projectRoot, runtime.host, args.code, {
@@ -11077,12 +12179,12 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "implementation_lookup",
-    "Jump to symbol definition. Find WHERE something is defined. Returns the authoritative source location(s). Prefers real implementation files over tests, docs, examples, and fixtures.",
+    "FIRST TOOL only for known-symbol definition questions. Returns authoritative source locations and prefers implementations over tests, docs, examples, and fixtures. Do not use for callers, callees, dependency paths, or code flow; use codebase_context with direction or from/to for those questions.",
     {
       query: z2.string().describe("Symbol name or natural language description (e.g., 'validateToken', 'where is the payment handler defined')"),
-      limit: z2.number().optional().default(5).describe("Maximum number of results"),
-      fileType: z2.string().optional().describe("Filter by file extension (e.g., 'ts', 'py')"),
-      directory: z2.string().optional().describe("Filter by directory path (e.g., 'src/utils')")
+      limit: allowNullAsUndefined(z2.number().optional().default(5)).describe("Maximum number of results"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils')")
     },
     async (args) => {
       const results = await implementationLookup(runtime.projectRoot, runtime.host, args.query, {
@@ -11095,12 +12197,16 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "call_graph",
-    "Query the call graph to find callers or callees of a function/method. Use to understand code flow and dependencies. Supports relationship types: Call, MethodCall, Constructor, Import, Inherits, Implements.",
+    "Use after identifying a symbol to find its direct callers or callees and understand code flow. Use implementation_lookup first if the symbol or definition is still ambiguous. Supports relationship types: Call, MethodCall, Constructor, Import, Inherits, Implements.",
     {
       name: z2.string().describe("Function or method name to query"),
-      direction: z2.enum(["callers", "callees"]).default("callers").describe("Direction: 'callers' finds who calls this function, 'callees' finds what this function calls"),
-      symbolId: z2.string().optional().describe("Symbol ID (required for 'callees' direction)"),
-      relationshipType: z2.enum(["Call", "MethodCall", "Constructor", "Import", "Inherits", "Implements"]).optional().describe("Filter by relationship type. Omit to show all.")
+      direction: allowNullAsUndefined(
+        z2.enum(["callers", "callees"]).default("callers")
+      ).describe("Direction: 'callers' finds who calls this function, 'callees' finds what this function calls"),
+      symbolId: allowNullAsUndefined(z2.string().optional()).describe("Symbol ID (required for 'callees' direction)"),
+      relationshipType: allowNullAsUndefined(
+        z2.enum(["Call", "MethodCall", "Constructor", "Import", "Inherits", "Implements"]).optional()
+      ).describe("Filter by relationship type. Omit to show all.")
     },
     async (args) => {
       if (args.direction === "callees") {
@@ -11116,27 +12222,29 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "call_graph_path",
-    "Find the shortest connection path between two symbols in the call graph. Returns the chain of calls connecting them.",
+    "Use after identifying both endpoint symbols to find the shortest known call path between them. Use codebase_peek or implementation_lookup first when either endpoint is unknown.",
     {
       from: z2.string().describe("Source function/method name (starting point)"),
       to: z2.string().describe("Target function/method name (destination)"),
-      maxDepth: z2.number().optional().default(10).describe("Maximum traversal depth (default: 10)")
+      maxDepth: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum traversal depth (default: 10)")
     },
     async (args) => {
-      const path26 = await getCallGraphPath(runtime.projectRoot, runtime.host, args.from, args.to, args.maxDepth);
-      return { content: [{ type: "text", text: formatCallGraphPath(args.from, args.to, path26) }] };
+      const path27 = await getCallGraphPath(runtime.projectRoot, runtime.host, args.from, args.to, args.maxDepth);
+      return { content: [{ type: "text", text: formatCallGraphPath(args.from, args.to, path27) }] };
     }
   );
   server.tool(
     "pr_impact",
-    "Analyze the impact of a pull request or branch by examining changed files, affected symbols, transitive callers, communities touched, hub nodes, and risk level. Use to understand blast radius before merging.",
+    "FIRST TOOL for pull-request or branch blast-radius questions. Analyzes changed files, affected symbols, transitive dependencies, communities, hub nodes, conflicts, and risk before merging.",
     {
-      pr: z2.number().optional().describe("Pull request number to analyze"),
-      branch: z2.string().optional().describe("Branch name to analyze (defaults to current branch)"),
-      maxDepth: z2.number().optional().default(5).describe("Maximum traversal depth for transitive callers (default: 5)"),
-      hubThreshold: z2.number().optional().default(10).describe("Minimum caller count to flag a symbol as a hub node (default: 10)"),
-      checkConflicts: z2.boolean().optional().default(false).describe("Check for conflicting open PRs touching the same communities (default: false)"),
-      direction: z2.enum(["callers", "callees", "both"]).optional().default("both").describe("Call-graph traversal direction: 'callers' for upstream, 'callees' for downstream, 'both' for union (default: both)")
+      pr: allowNullAsUndefined(z2.number().optional()).describe("Pull request number to analyze"),
+      branch: allowNullAsUndefined(z2.string().optional()).describe("Branch name to analyze (defaults to current branch)"),
+      maxDepth: allowNullAsUndefined(z2.number().optional().default(5)).describe("Maximum traversal depth for transitive callers (default: 5)"),
+      hubThreshold: allowNullAsUndefined(z2.number().optional().default(10)).describe("Minimum caller count to flag a symbol as a hub node (default: 10)"),
+      checkConflicts: allowNullAsUndefined(z2.boolean().optional().default(false)).describe("Check for conflicting open PRs touching the same communities (default: false)"),
+      direction: allowNullAsUndefined(
+        z2.enum(["callers", "callees", "both"]).optional().default("both")
+      ).describe("Call-graph traversal direction: 'callers' for upstream, 'callees' for downstream, 'both' for union (default: both)")
     },
     async (args) => {
       try {
@@ -11158,8 +12266,12 @@ ${formatSearchResults(results)}` }] };
 }
 
 // src/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 low-token locations first and routes to definitions or call-graph helpers when symbol intent is present. Use codebase_peek for direct conceptual location lookup, implementation_lookup for known-symbol definition questions, and codebase_search only when full semantic code content is needed. 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 getPackageVersion() {
-  const raw = JSON.parse(readFileSync10(new URL("../package.json", import.meta.url), "utf-8"));
+  const raw = JSON.parse(readFileSync11(new URL("../package.json", import.meta.url), "utf-8"));
   if (raw && typeof raw === "object" && "version" in raw && typeof raw.version === "string") {
     return raw.version;
   }
@@ -11169,6 +12281,8 @@ function createMcpServer(projectRoot, config, host = "opencode") {
   const server = new McpServer({
     name: "opencode-codebase-index",
     version: getPackageVersion()
+  }, {
+    instructions: getServerInstructions(host)
   });
   initializeTools(projectRoot, config, host);
   registerMcpTools(server, {
@@ -11180,18 +12294,37 @@ function createMcpServer(projectRoot, config, host = "opencode") {
 }
 
 // src/utils/auto-index.ts
+var INITIAL_RETRY_DELAY_MS = 50;
+var MAX_RETRY_DELAY_MS = 500;
+var autoIndexStates = /* @__PURE__ */ new WeakMap();
 function getErrorMessage3(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function startAutoIndex(indexer, projectRoot) {
-  indexer.initialize().then(() => {
-    indexer.index().catch((error) => {
-      console.error(`[codebase-index] Auto-index failed for "${projectRoot}": ${getErrorMessage3(error)}`);
-    });
+function runAutoIndex(indexer, projectRoot, state) {
+  void indexer.index().then(() => {
+    autoIndexStates.delete(indexer);
   }).catch((error) => {
-    console.error(`[codebase-index] Auto-index initialization failed for "${projectRoot}": ${getErrorMessage3(error)}`);
+    if (!isTransientIndexLockContention(error)) {
+      autoIndexStates.delete(indexer);
+      console.error(`[codebase-index] Auto-index failed for "${projectRoot}": ${getErrorMessage3(error)}`);
+      return;
+    }
+    const retryDelayMs = state.retryDelayMs;
+    state.retryDelayMs = Math.min(retryDelayMs * 2, MAX_RETRY_DELAY_MS);
+    const retryTimer = setTimeout(() => {
+      runAutoIndex(indexer, projectRoot, state);
+    }, retryDelayMs);
+    retryTimer.unref?.();
   });
 }
+function startAutoIndex(indexer, projectRoot) {
+  if (autoIndexStates.has(indexer)) return;
+  const state = {
+    retryDelayMs: INITIAL_RETRY_DELAY_MS
+  };
+  autoIndexStates.set(indexer, state);
+  runAutoIndex(indexer, projectRoot, state);
+}
 
 // node_modules/chokidar/index.js
 import { EventEmitter as EventEmitter2 } from "events";
@@ -11283,7 +12416,7 @@ var ReaddirpStream = class extends Readable {
     this._directoryFilter = normalizeFilter(opts.directoryFilter);
     const statMethod = opts.lstat ? lstat : stat;
     if (wantBigintFsStats) {
-      this._stat = (path26) => statMethod(path26, { bigint: true });
+      this._stat = (path27) => statMethod(path27, { bigint: true });
     } else {
       this._stat = statMethod;
     }
@@ -11308,8 +12441,8 @@ var ReaddirpStream = class extends Readable {
         const par = this.parent;
         const fil = par && par.files;
         if (fil && fil.length > 0) {
-          const { path: path26, depth } = par;
-          const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path26));
+          const { path: path27, depth } = par;
+          const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path27));
           const awaited = await Promise.all(slice);
           for (const entry of awaited) {
             if (!entry)
@@ -11349,20 +12482,20 @@ var ReaddirpStream = class extends Readable {
       this.reading = false;
     }
   }
-  async _exploreDir(path26, depth) {
+  async _exploreDir(path27, depth) {
     let files;
     try {
-      files = await readdir(path26, this._rdOptions);
+      files = await readdir(path27, this._rdOptions);
     } catch (error) {
       this._onError(error);
     }
-    return { files, depth, path: path26 };
+    return { files, depth, path: path27 };
   }
-  async _formatEntry(dirent, path26) {
+  async _formatEntry(dirent, path27) {
     let entry;
     const basename5 = this._isDirent ? dirent.name : dirent;
     try {
-      const fullPath = presolve(pjoin(path26, basename5));
+      const fullPath = presolve(pjoin(path27, basename5));
       entry = { path: prelative(this._root, fullPath), fullPath, basename: basename5 };
       entry[this._statsProp] = this._isDirent ? dirent : await this._stat(fullPath);
     } catch (err) {
@@ -11762,16 +12895,16 @@ var delFromSet = (main2, prop, item) => {
 };
 var isEmptySet = (val) => val instanceof Set ? val.size === 0 : !val;
 var FsWatchInstances = /* @__PURE__ */ new Map();
-function createFsWatchInstance(path26, options, listener, errHandler, emitRaw) {
+function createFsWatchInstance(path27, options, listener, errHandler, emitRaw) {
   const handleEvent = (rawEvent, evPath) => {
-    listener(path26);
-    emitRaw(rawEvent, evPath, { watchedPath: path26 });
-    if (evPath && path26 !== evPath) {
-      fsWatchBroadcast(sp.resolve(path26, evPath), KEY_LISTENERS, sp.join(path26, evPath));
+    listener(path27);
+    emitRaw(rawEvent, evPath, { watchedPath: path27 });
+    if (evPath && path27 !== evPath) {
+      fsWatchBroadcast(sp.resolve(path27, evPath), KEY_LISTENERS, sp.join(path27, evPath));
     }
   };
   try {
-    return fs_watch(path26, {
+    return fs_watch(path27, {
       persistent: options.persistent
     }, handleEvent);
   } catch (error) {
@@ -11787,12 +12920,12 @@ var fsWatchBroadcast = (fullPath, listenerType, val1, val2, val3) => {
     listener(val1, val2, val3);
   });
 };
-var setFsWatchListener = (path26, fullPath, options, handlers) => {
+var setFsWatchListener = (path27, fullPath, options, handlers) => {
   const { listener, errHandler, rawEmitter } = handlers;
   let cont = FsWatchInstances.get(fullPath);
   let watcher;
   if (!options.persistent) {
-    watcher = createFsWatchInstance(path26, options, listener, errHandler, rawEmitter);
+    watcher = createFsWatchInstance(path27, options, listener, errHandler, rawEmitter);
     if (!watcher)
       return;
     return watcher.close.bind(watcher);
@@ -11803,7 +12936,7 @@ var setFsWatchListener = (path26, fullPath, options, handlers) => {
     addAndConvert(cont, KEY_RAW, rawEmitter);
   } else {
     watcher = createFsWatchInstance(
-      path26,
+      path27,
       options,
       fsWatchBroadcast.bind(null, fullPath, KEY_LISTENERS),
       errHandler,
@@ -11818,7 +12951,7 @@ var setFsWatchListener = (path26, fullPath, options, handlers) => {
         cont.watcherUnusable = true;
       if (isWindows && error.code === "EPERM") {
         try {
-          const fd = await open(path26, "r");
+          const fd = await open(path27, "r");
           await fd.close();
           broadcastErr(error);
         } catch (err) {
@@ -11849,7 +12982,7 @@ var setFsWatchListener = (path26, fullPath, options, handlers) => {
   };
 };
 var FsWatchFileInstances = /* @__PURE__ */ new Map();
-var setFsWatchFileListener = (path26, fullPath, options, handlers) => {
+var setFsWatchFileListener = (path27, fullPath, options, handlers) => {
   const { listener, rawEmitter } = handlers;
   let cont = FsWatchFileInstances.get(fullPath);
   const copts = cont && cont.options;
@@ -11871,7 +13004,7 @@ var setFsWatchFileListener = (path26, fullPath, options, handlers) => {
         });
         const currmtime = curr.mtimeMs;
         if (curr.size !== prev.size || currmtime > prev.mtimeMs || currmtime === 0) {
-          foreach(cont.listeners, (listener2) => listener2(path26, curr));
+          foreach(cont.listeners, (listener2) => listener2(path27, curr));
         }
       })
     };
@@ -11901,13 +13034,13 @@ var NodeFsHandler = class {
    * @param listener on fs change
    * @returns closer for the watcher instance
    */
-  _watchWithNodeFs(path26, listener) {
+  _watchWithNodeFs(path27, listener) {
     const opts = this.fsw.options;
-    const directory = sp.dirname(path26);
-    const basename5 = sp.basename(path26);
+    const directory = sp.dirname(path27);
+    const basename5 = sp.basename(path27);
     const parent = this.fsw._getWatchedDir(directory);
     parent.add(basename5);
-    const absolutePath = sp.resolve(path26);
+    const absolutePath = sp.resolve(path27);
     const options = {
       persistent: opts.persistent
     };
@@ -11917,12 +13050,12 @@ var NodeFsHandler = class {
     if (opts.usePolling) {
       const enableBin = opts.interval !== opts.binaryInterval;
       options.interval = enableBin && isBinaryPath(basename5) ? opts.binaryInterval : opts.interval;
-      closer = setFsWatchFileListener(path26, absolutePath, options, {
+      closer = setFsWatchFileListener(path27, absolutePath, options, {
         listener,
         rawEmitter: this.fsw._emitRaw
       });
     } else {
-      closer = setFsWatchListener(path26, absolutePath, options, {
+      closer = setFsWatchListener(path27, absolutePath, options, {
         listener,
         errHandler: this._boundHandleError,
         rawEmitter: this.fsw._emitRaw
@@ -11944,7 +13077,7 @@ var NodeFsHandler = class {
     let prevStats = stats;
     if (parent.has(basename5))
       return;
-    const listener = async (path26, newStats) => {
+    const listener = async (path27, newStats) => {
       if (!this.fsw._throttle(THROTTLE_MODE_WATCH, file, 5))
         return;
       if (!newStats || newStats.mtimeMs === 0) {
@@ -11958,11 +13091,11 @@ var NodeFsHandler = class {
             this.fsw._emit(EV.CHANGE, file, newStats2);
           }
           if ((isMacos || isLinux || isFreeBSD) && prevStats.ino !== newStats2.ino) {
-            this.fsw._closeFile(path26);
+            this.fsw._closeFile(path27);
             prevStats = newStats2;
             const closer2 = this._watchWithNodeFs(file, listener);
             if (closer2)
-              this.fsw._addPathCloser(path26, closer2);
+              this.fsw._addPathCloser(path27, closer2);
           } else {
             prevStats = newStats2;
           }
@@ -11994,7 +13127,7 @@ var NodeFsHandler = class {
    * @param item basename of this item
    * @returns true if no more processing is needed for this entry.
    */
-  async _handleSymlink(entry, directory, path26, item) {
+  async _handleSymlink(entry, directory, path27, item) {
     if (this.fsw.closed) {
       return;
     }
@@ -12004,7 +13137,7 @@ var NodeFsHandler = class {
       this.fsw._incrReadyCount();
       let linkPath;
       try {
-        linkPath = await fsrealpath(path26);
+        linkPath = await fsrealpath(path27);
       } catch (e) {
         this.fsw._emitReady();
         return true;
@@ -12014,12 +13147,12 @@ var NodeFsHandler = class {
       if (dir.has(item)) {
         if (this.fsw._symlinkPaths.get(full) !== linkPath) {
           this.fsw._symlinkPaths.set(full, linkPath);
-          this.fsw._emit(EV.CHANGE, path26, entry.stats);
+          this.fsw._emit(EV.CHANGE, path27, entry.stats);
         }
       } else {
         dir.add(item);
         this.fsw._symlinkPaths.set(full, linkPath);
-        this.fsw._emit(EV.ADD, path26, entry.stats);
+        this.fsw._emit(EV.ADD, path27, entry.stats);
       }
       this.fsw._emitReady();
       return true;
@@ -12049,9 +13182,9 @@ var NodeFsHandler = class {
         return;
       }
       const item = entry.path;
-      let path26 = sp.join(directory, item);
+      let path27 = sp.join(directory, item);
       current.add(item);
-      if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path26, item)) {
+      if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path27, item)) {
         return;
       }
       if (this.fsw.closed) {
@@ -12060,8 +13193,8 @@ var NodeFsHandler = class {
       }
       if (item === target || !target && !previous.has(item)) {
         this.fsw._incrReadyCount();
-        path26 = sp.join(dir, sp.relative(dir, path26));
-        this._addToNodeFs(path26, initialAdd, wh, depth + 1);
+        path27 = sp.join(dir, sp.relative(dir, path27));
+        this._addToNodeFs(path27, initialAdd, wh, depth + 1);
       }
     }).on(EV.ERROR, this._boundHandleError);
     return new Promise((resolve15, reject) => {
@@ -12130,13 +13263,13 @@ var NodeFsHandler = class {
    * @param depth Child path actually targeted for watch
    * @param target Child path actually targeted for watch
    */
-  async _addToNodeFs(path26, initialAdd, priorWh, depth, target) {
+  async _addToNodeFs(path27, initialAdd, priorWh, depth, target) {
     const ready = this.fsw._emitReady;
-    if (this.fsw._isIgnored(path26) || this.fsw.closed) {
+    if (this.fsw._isIgnored(path27) || this.fsw.closed) {
       ready();
       return false;
     }
-    const wh = this.fsw._getWatchHelpers(path26);
+    const wh = this.fsw._getWatchHelpers(path27);
     if (priorWh) {
       wh.filterPath = (entry) => priorWh.filterPath(entry);
       wh.filterDir = (entry) => priorWh.filterDir(entry);
@@ -12152,8 +13285,8 @@ var NodeFsHandler = class {
       const follow = this.fsw.options.followSymlinks;
       let closer;
       if (stats.isDirectory()) {
-        const absPath = sp.resolve(path26);
-        const targetPath = follow ? await fsrealpath(path26) : path26;
+        const absPath = sp.resolve(path27);
+        const targetPath = follow ? await fsrealpath(path27) : path27;
         if (this.fsw.closed)
           return;
         closer = await this._handleDir(wh.watchPath, stats, initialAdd, depth, target, wh, targetPath);
@@ -12163,29 +13296,29 @@ var NodeFsHandler = class {
           this.fsw._symlinkPaths.set(absPath, targetPath);
         }
       } else if (stats.isSymbolicLink()) {
-        const targetPath = follow ? await fsrealpath(path26) : path26;
+        const targetPath = follow ? await fsrealpath(path27) : path27;
         if (this.fsw.closed)
           return;
         const parent = sp.dirname(wh.watchPath);
         this.fsw._getWatchedDir(parent).add(wh.watchPath);
         this.fsw._emit(EV.ADD, wh.watchPath, stats);
-        closer = await this._handleDir(parent, stats, initialAdd, depth, path26, wh, targetPath);
+        closer = await this._handleDir(parent, stats, initialAdd, depth, path27, wh, targetPath);
         if (this.fsw.closed)
           return;
         if (targetPath !== void 0) {
-          this.fsw._symlinkPaths.set(sp.resolve(path26), targetPath);
+          this.fsw._symlinkPaths.set(sp.resolve(path27), targetPath);
         }
       } else {
         closer = this._handleFile(wh.watchPath, stats, initialAdd);
       }
       ready();
       if (closer)
-        this.fsw._addPathCloser(path26, closer);
+        this.fsw._addPathCloser(path27, closer);
       return false;
     } catch (error) {
       if (this.fsw._handleError(error)) {
         ready();
-        return path26;
+        return path27;
       }
     }
   }
@@ -12228,24 +13361,24 @@ function createPattern(matcher) {
   }
   return () => false;
 }
-function normalizePath2(path26) {
-  if (typeof path26 !== "string")
+function normalizePath2(path27) {
+  if (typeof path27 !== "string")
     throw new Error("string expected");
-  path26 = sp2.normalize(path26);
-  path26 = path26.replace(/\\/g, "/");
+  path27 = sp2.normalize(path27);
+  path27 = path27.replace(/\\/g, "/");
   let prepend = false;
-  if (path26.startsWith("//"))
+  if (path27.startsWith("//"))
     prepend = true;
-  path26 = path26.replace(DOUBLE_SLASH_RE, "/");
+  path27 = path27.replace(DOUBLE_SLASH_RE, "/");
   if (prepend)
-    path26 = "/" + path26;
-  return path26;
+    path27 = "/" + path27;
+  return path27;
 }
 function matchPatterns(patterns, testString, stats) {
-  const path26 = normalizePath2(testString);
+  const path27 = normalizePath2(testString);
   for (let index = 0; index < patterns.length; index++) {
     const pattern = patterns[index];
-    if (pattern(path26, stats)) {
+    if (pattern(path27, stats)) {
       return true;
     }
   }
@@ -12283,19 +13416,19 @@ var toUnix = (string) => {
   }
   return str;
 };
-var normalizePathToUnix = (path26) => toUnix(sp2.normalize(toUnix(path26)));
-var normalizeIgnored = (cwd = "") => (path26) => {
-  if (typeof path26 === "string") {
-    return normalizePathToUnix(sp2.isAbsolute(path26) ? path26 : sp2.join(cwd, path26));
+var normalizePathToUnix = (path27) => toUnix(sp2.normalize(toUnix(path27)));
+var normalizeIgnored = (cwd = "") => (path27) => {
+  if (typeof path27 === "string") {
+    return normalizePathToUnix(sp2.isAbsolute(path27) ? path27 : sp2.join(cwd, path27));
   } else {
-    return path26;
+    return path27;
   }
 };
-var getAbsolutePath = (path26, cwd) => {
-  if (sp2.isAbsolute(path26)) {
-    return path26;
+var getAbsolutePath = (path27, cwd) => {
+  if (sp2.isAbsolute(path27)) {
+    return path27;
   }
-  return sp2.join(cwd, path26);
+  return sp2.join(cwd, path27);
 };
 var EMPTY_SET = Object.freeze(/* @__PURE__ */ new Set());
 var DirEntry = class {
@@ -12360,10 +13493,10 @@ var WatchHelper = class {
   dirParts;
   followSymlinks;
   statMethod;
-  constructor(path26, follow, fsw) {
+  constructor(path27, follow, fsw) {
     this.fsw = fsw;
-    const watchPath = path26;
-    this.path = path26 = path26.replace(REPLACER_RE, "");
+    const watchPath = path27;
+    this.path = path27 = path27.replace(REPLACER_RE, "");
     this.watchPath = watchPath;
     this.fullWatchPath = sp2.resolve(watchPath);
     this.dirParts = [];
@@ -12503,20 +13636,20 @@ var FSWatcher = class extends EventEmitter2 {
     this._closePromise = void 0;
     let paths = unifyPaths(paths_);
     if (cwd) {
-      paths = paths.map((path26) => {
-        const absPath = getAbsolutePath(path26, cwd);
+      paths = paths.map((path27) => {
+        const absPath = getAbsolutePath(path27, cwd);
         return absPath;
       });
     }
-    paths.forEach((path26) => {
-      this._removeIgnoredPath(path26);
+    paths.forEach((path27) => {
+      this._removeIgnoredPath(path27);
     });
     this._userIgnored = void 0;
     if (!this._readyCount)
       this._readyCount = 0;
     this._readyCount += paths.length;
-    Promise.all(paths.map(async (path26) => {
-      const res = await this._nodeFsHandler._addToNodeFs(path26, !_internal, void 0, 0, _origAdd);
+    Promise.all(paths.map(async (path27) => {
+      const res = await this._nodeFsHandler._addToNodeFs(path27, !_internal, void 0, 0, _origAdd);
       if (res)
         this._emitReady();
       return res;
@@ -12538,17 +13671,17 @@ var FSWatcher = class extends EventEmitter2 {
       return this;
     const paths = unifyPaths(paths_);
     const { cwd } = this.options;
-    paths.forEach((path26) => {
-      if (!sp2.isAbsolute(path26) && !this._closers.has(path26)) {
+    paths.forEach((path27) => {
+      if (!sp2.isAbsolute(path27) && !this._closers.has(path27)) {
         if (cwd)
-          path26 = sp2.join(cwd, path26);
-        path26 = sp2.resolve(path26);
+          path27 = sp2.join(cwd, path27);
+        path27 = sp2.resolve(path27);
       }
-      this._closePath(path26);
-      this._addIgnoredPath(path26);
-      if (this._watched.has(path26)) {
+      this._closePath(path27);
+      this._addIgnoredPath(path27);
+      if (this._watched.has(path27)) {
         this._addIgnoredPath({
-          path: path26,
+          path: path27,
           recursive: true
         });
       }
@@ -12612,38 +13745,38 @@ var FSWatcher = class extends EventEmitter2 {
    * @param stats arguments to be passed with event
    * @returns the error if defined, otherwise the value of the FSWatcher instance's `closed` flag
    */
-  async _emit(event, path26, stats) {
+  async _emit(event, path27, stats) {
     if (this.closed)
       return;
     const opts = this.options;
     if (isWindows)
-      path26 = sp2.normalize(path26);
+      path27 = sp2.normalize(path27);
     if (opts.cwd)
-      path26 = sp2.relative(opts.cwd, path26);
-    const args = [path26];
+      path27 = sp2.relative(opts.cwd, path27);
+    const args = [path27];
     if (stats != null)
       args.push(stats);
     const awf = opts.awaitWriteFinish;
     let pw;
-    if (awf && (pw = this._pendingWrites.get(path26))) {
+    if (awf && (pw = this._pendingWrites.get(path27))) {
       pw.lastChange = /* @__PURE__ */ new Date();
       return this;
     }
     if (opts.atomic) {
       if (event === EVENTS.UNLINK) {
-        this._pendingUnlinks.set(path26, [event, ...args]);
+        this._pendingUnlinks.set(path27, [event, ...args]);
         setTimeout(() => {
-          this._pendingUnlinks.forEach((entry, path27) => {
+          this._pendingUnlinks.forEach((entry, path28) => {
             this.emit(...entry);
             this.emit(EVENTS.ALL, ...entry);
-            this._pendingUnlinks.delete(path27);
+            this._pendingUnlinks.delete(path28);
           });
         }, typeof opts.atomic === "number" ? opts.atomic : 100);
         return this;
       }
-      if (event === EVENTS.ADD && this._pendingUnlinks.has(path26)) {
+      if (event === EVENTS.ADD && this._pendingUnlinks.has(path27)) {
         event = EVENTS.CHANGE;
-        this._pendingUnlinks.delete(path26);
+        this._pendingUnlinks.delete(path27);
       }
     }
     if (awf && (event === EVENTS.ADD || event === EVENTS.CHANGE) && this._readyEmitted) {
@@ -12661,16 +13794,16 @@ var FSWatcher = class extends EventEmitter2 {
           this.emitWithAll(event, args);
         }
       };
-      this._awaitWriteFinish(path26, awf.stabilityThreshold, event, awfEmit);
+      this._awaitWriteFinish(path27, awf.stabilityThreshold, event, awfEmit);
       return this;
     }
     if (event === EVENTS.CHANGE) {
-      const isThrottled = !this._throttle(EVENTS.CHANGE, path26, 50);
+      const isThrottled = !this._throttle(EVENTS.CHANGE, path27, 50);
       if (isThrottled)
         return this;
     }
     if (opts.alwaysStat && stats === void 0 && (event === EVENTS.ADD || event === EVENTS.ADD_DIR || event === EVENTS.CHANGE)) {
-      const fullPath = opts.cwd ? sp2.join(opts.cwd, path26) : path26;
+      const fullPath = opts.cwd ? sp2.join(opts.cwd, path27) : path27;
       let stats2;
       try {
         stats2 = await stat3(fullPath);
@@ -12701,23 +13834,23 @@ var FSWatcher = class extends EventEmitter2 {
    * @param timeout duration of time to suppress duplicate actions
    * @returns tracking object or false if action should be suppressed
    */
-  _throttle(actionType, path26, timeout) {
+  _throttle(actionType, path27, timeout) {
     if (!this._throttled.has(actionType)) {
       this._throttled.set(actionType, /* @__PURE__ */ new Map());
     }
     const action = this._throttled.get(actionType);
     if (!action)
       throw new Error("invalid throttle");
-    const actionPath = action.get(path26);
+    const actionPath = action.get(path27);
     if (actionPath) {
       actionPath.count++;
       return false;
     }
     let timeoutObject;
     const clear = () => {
-      const item = action.get(path26);
+      const item = action.get(path27);
       const count = item ? item.count : 0;
-      action.delete(path26);
+      action.delete(path27);
       clearTimeout(timeoutObject);
       if (item)
         clearTimeout(item.timeoutObject);
@@ -12725,7 +13858,7 @@ var FSWatcher = class extends EventEmitter2 {
     };
     timeoutObject = setTimeout(clear, timeout);
     const thr = { timeoutObject, clear, count: 0 };
-    action.set(path26, thr);
+    action.set(path27, thr);
     return thr;
   }
   _incrReadyCount() {
@@ -12739,44 +13872,44 @@ var FSWatcher = class extends EventEmitter2 {
    * @param event
    * @param awfEmit Callback to be called when ready for event to be emitted.
    */
-  _awaitWriteFinish(path26, threshold, event, awfEmit) {
+  _awaitWriteFinish(path27, threshold, event, awfEmit) {
     const awf = this.options.awaitWriteFinish;
     if (typeof awf !== "object")
       return;
     const pollInterval = awf.pollInterval;
     let timeoutHandler;
-    let fullPath = path26;
-    if (this.options.cwd && !sp2.isAbsolute(path26)) {
-      fullPath = sp2.join(this.options.cwd, path26);
+    let fullPath = path27;
+    if (this.options.cwd && !sp2.isAbsolute(path27)) {
+      fullPath = sp2.join(this.options.cwd, path27);
     }
     const now = /* @__PURE__ */ new Date();
     const writes = this._pendingWrites;
     function awaitWriteFinishFn(prevStat) {
       statcb(fullPath, (err, curStat) => {
-        if (err || !writes.has(path26)) {
+        if (err || !writes.has(path27)) {
           if (err && err.code !== "ENOENT")
             awfEmit(err);
           return;
         }
         const now2 = Number(/* @__PURE__ */ new Date());
         if (prevStat && curStat.size !== prevStat.size) {
-          writes.get(path26).lastChange = now2;
+          writes.get(path27).lastChange = now2;
         }
-        const pw = writes.get(path26);
+        const pw = writes.get(path27);
         const df = now2 - pw.lastChange;
         if (df >= threshold) {
-          writes.delete(path26);
+          writes.delete(path27);
           awfEmit(void 0, curStat);
         } else {
           timeoutHandler = setTimeout(awaitWriteFinishFn, pollInterval, curStat);
         }
       });
     }
-    if (!writes.has(path26)) {
-      writes.set(path26, {
+    if (!writes.has(path27)) {
+      writes.set(path27, {
         lastChange: now,
         cancelWait: () => {
-          writes.delete(path26);
+          writes.delete(path27);
           clearTimeout(timeoutHandler);
           return event;
         }
@@ -12787,8 +13920,8 @@ var FSWatcher = class extends EventEmitter2 {
   /**
    * Determines whether user has asked to ignore this path.
    */
-  _isIgnored(path26, stats) {
-    if (this.options.atomic && DOT_RE.test(path26))
+  _isIgnored(path27, stats) {
+    if (this.options.atomic && DOT_RE.test(path27))
       return true;
     if (!this._userIgnored) {
       const { cwd } = this.options;
@@ -12798,17 +13931,17 @@ var FSWatcher = class extends EventEmitter2 {
       const list = [...ignoredPaths.map(normalizeIgnored(cwd)), ...ignored];
       this._userIgnored = anymatch(list, void 0);
     }
-    return this._userIgnored(path26, stats);
+    return this._userIgnored(path27, stats);
   }
-  _isntIgnored(path26, stat4) {
-    return !this._isIgnored(path26, stat4);
+  _isntIgnored(path27, stat4) {
+    return !this._isIgnored(path27, stat4);
   }
   /**
    * Provides a set of common helpers and properties relating to symlink handling.
    * @param path file or directory pattern being watched
    */
-  _getWatchHelpers(path26) {
-    return new WatchHelper(path26, this.options.followSymlinks, this);
+  _getWatchHelpers(path27) {
+    return new WatchHelper(path27, this.options.followSymlinks, this);
   }
   // Directory helpers
   // -----------------
@@ -12840,63 +13973,63 @@ var FSWatcher = class extends EventEmitter2 {
    * @param item      base path of item/directory
    */
   _remove(directory, item, isDirectory) {
-    const path26 = sp2.join(directory, item);
-    const fullPath = sp2.resolve(path26);
-    isDirectory = isDirectory != null ? isDirectory : this._watched.has(path26) || this._watched.has(fullPath);
-    if (!this._throttle("remove", path26, 100))
+    const path27 = sp2.join(directory, item);
+    const fullPath = sp2.resolve(path27);
+    isDirectory = isDirectory != null ? isDirectory : this._watched.has(path27) || this._watched.has(fullPath);
+    if (!this._throttle("remove", path27, 100))
       return;
     if (!isDirectory && this._watched.size === 1) {
       this.add(directory, item, true);
     }
-    const wp = this._getWatchedDir(path26);
+    const wp = this._getWatchedDir(path27);
     const nestedDirectoryChildren = wp.getChildren();
-    nestedDirectoryChildren.forEach((nested) => this._remove(path26, nested));
+    nestedDirectoryChildren.forEach((nested) => this._remove(path27, nested));
     const parent = this._getWatchedDir(directory);
     const wasTracked = parent.has(item);
     parent.remove(item);
     if (this._symlinkPaths.has(fullPath)) {
       this._symlinkPaths.delete(fullPath);
     }
-    let relPath = path26;
+    let relPath = path27;
     if (this.options.cwd)
-      relPath = sp2.relative(this.options.cwd, path26);
+      relPath = sp2.relative(this.options.cwd, path27);
     if (this.options.awaitWriteFinish && this._pendingWrites.has(relPath)) {
       const event = this._pendingWrites.get(relPath).cancelWait();
       if (event === EVENTS.ADD)
         return;
     }
-    this._watched.delete(path26);
+    this._watched.delete(path27);
     this._watched.delete(fullPath);
     const eventName = isDirectory ? EVENTS.UNLINK_DIR : EVENTS.UNLINK;
-    if (wasTracked && !this._isIgnored(path26))
-      this._emit(eventName, path26);
-    this._closePath(path26);
+    if (wasTracked && !this._isIgnored(path27))
+      this._emit(eventName, path27);
+    this._closePath(path27);
   }
   /**
    * Closes all watchers for a path
    */
-  _closePath(path26) {
-    this._closeFile(path26);
-    const dir = sp2.dirname(path26);
-    this._getWatchedDir(dir).remove(sp2.basename(path26));
+  _closePath(path27) {
+    this._closeFile(path27);
+    const dir = sp2.dirname(path27);
+    this._getWatchedDir(dir).remove(sp2.basename(path27));
   }
   /**
    * Closes only file-specific watchers
    */
-  _closeFile(path26) {
-    const closers = this._closers.get(path26);
+  _closeFile(path27) {
+    const closers = this._closers.get(path27);
     if (!closers)
       return;
     closers.forEach((closer) => closer());
-    this._closers.delete(path26);
+    this._closers.delete(path27);
   }
-  _addPathCloser(path26, closer) {
+  _addPathCloser(path27, closer) {
     if (!closer)
       return;
-    let list = this._closers.get(path26);
+    let list = this._closers.get(path27);
     if (!list) {
       list = [];
-      this._closers.set(path26, list);
+      this._closers.set(path27, list);
     }
     list.push(closer);
   }
@@ -12926,7 +14059,7 @@ function watch(paths, options = {}) {
 var chokidar_default = { watch, FSWatcher };
 
 // src/watcher/file-watcher.ts
-import * as path21 from "path";
+import * as path22 from "path";
 var FileWatcher = class {
   watcher = null;
   projectRoot;
@@ -12937,6 +14070,8 @@ var FileWatcher = class {
   debounceTimer = null;
   debounceMs = 1e3;
   onChanges = null;
+  readyPromise = null;
+  resolveReady = null;
   constructor(projectRoot, config, host = "opencode", options = {}) {
     this.projectRoot = projectRoot;
     this.config = config;
@@ -12952,15 +14087,15 @@ var FileWatcher = class {
     const watchTargets = this.configPath ? [this.projectRoot, this.configPath] : this.projectRoot;
     this.watcher = chokidar_default.watch(watchTargets, {
       ignored: (filePath) => {
-        const relativePath = path21.relative(this.projectRoot, filePath);
+        const relativePath = path22.relative(this.projectRoot, filePath);
         if (!relativePath) return false;
         if (this.isProjectConfigPathOrAncestor(relativePath)) {
           return false;
         }
-        if (hasFilteredPathSegment(relativePath, path21.sep)) {
+        if (hasFilteredPathSegment(relativePath, path22.sep)) {
           return true;
         }
-        if (isRestrictedDirectory(relativePath, path21.sep)) {
+        if (isRestrictedDirectory(relativePath, path22.sep)) {
           return true;
         }
         if (ignoreFilter.ignores(relativePath)) {
@@ -12975,6 +14110,13 @@ var FileWatcher = class {
         pollInterval: 100
       }
     });
+    this.readyPromise = new Promise((resolve15) => {
+      this.resolveReady = resolve15;
+    });
+    this.watcher.once("ready", () => {
+      this.resolveReady?.();
+      this.resolveReady = null;
+    });
     this.watcher.on("error", (error) => {
       const err = error instanceof Error ? error : null;
       if (err?.code === "EPERM" || err?.code === "EACCES") {
@@ -13006,24 +14148,24 @@ var FileWatcher = class {
     this.scheduleFlush();
   }
   isProjectConfigPath(filePath) {
-    const relativePath = path21.relative(this.projectRoot, filePath);
-    const normalizedRelativePath = path21.normalize(relativePath);
+    const relativePath = path22.relative(this.projectRoot, filePath);
+    const normalizedRelativePath = path22.normalize(relativePath);
     return this.getProjectConfigRelativePaths().some((configPath) => configPath === normalizedRelativePath);
   }
   isProjectConfigPathOrAncestor(relativePath) {
-    const normalizedRelativePath = path21.normalize(relativePath);
+    const normalizedRelativePath = path22.normalize(relativePath);
     return this.getProjectConfigRelativePaths().some(
-      (configPath) => configPath === normalizedRelativePath || configPath.startsWith(`${normalizedRelativePath}${path21.sep}`)
+      (configPath) => configPath === normalizedRelativePath || configPath.startsWith(`${normalizedRelativePath}${path22.sep}`)
     );
   }
   getProjectConfigRelativePaths() {
     if (this.configPath) {
-      return [path21.normalize(path21.relative(this.projectRoot, this.configPath))];
+      return [path22.normalize(path22.relative(this.projectRoot, this.configPath))];
     }
     return [
       resolveProjectConfigPath(this.projectRoot, this.host),
       resolveWritableProjectConfigPath(this.projectRoot, this.host)
-    ].map((configPath) => path21.normalize(path21.relative(this.projectRoot, configPath)));
+    ].map((configPath) => path22.normalize(path22.relative(this.projectRoot, configPath)));
   }
   scheduleFlush() {
     if (this.debounceTimer) {
@@ -13038,7 +14180,7 @@ var FileWatcher = class {
       return;
     }
     const changes = Array.from(this.pendingChanges.entries()).map(
-      ([path26, type]) => ({ path: path26, type })
+      ([path27, type]) => ({ path: path27, type })
     );
     this.pendingChanges.clear();
     try {
@@ -13047,25 +14189,32 @@ var FileWatcher = class {
       console.error("Error handling file changes:", error);
     }
   }
-  stop() {
+  async stop() {
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
       this.debounceTimer = null;
     }
     if (this.watcher) {
-      this.watcher.close();
+      const watcher = this.watcher;
       this.watcher = null;
+      await watcher.close();
     }
+    this.resolveReady?.();
+    this.resolveReady = null;
+    this.readyPromise = null;
     this.pendingChanges.clear();
     this.onChanges = null;
   }
   isRunning() {
     return this.watcher !== null;
   }
+  async waitUntilReady() {
+    await (this.readyPromise ?? Promise.resolve());
+  }
 };
 
 // src/watcher/git-head-watcher.ts
-import * as path22 from "path";
+import * as path23 from "path";
 var GitHeadWatcher = class {
   watcher = null;
   projectRoot;
@@ -13087,7 +14236,7 @@ var GitHeadWatcher = class {
     this.onBranchChange = handler;
     this.currentBranch = getCurrentBranch(this.projectRoot);
     const headPath = getHeadPath(this.projectRoot);
-    const refsPath = path22.join(this.projectRoot, ".git", "refs", "heads");
+    const refsPath = path23.join(this.projectRoot, ".git", "refs", "heads");
     this.watcher = chokidar_default.watch([headPath, refsPath], {
       persistent: true,
       ignoreInitial: true,
@@ -13124,14 +14273,15 @@ var GitHeadWatcher = class {
   getCurrentBranch() {
     return this.currentBranch;
   }
-  stop() {
+  async stop() {
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
       this.debounceTimer = null;
     }
     if (this.watcher) {
-      this.watcher.close();
+      const watcher = this.watcher;
       this.watcher = null;
+      await watcher.close();
     }
     this.onBranchChange = null;
   }
@@ -13149,6 +14299,8 @@ var BackgroundReindexer = class {
   running = false;
   pending = false;
   stopped = false;
+  retryTimer = null;
+  retryDelayMs = 50;
   request() {
     if (this.stopped) {
       return;
@@ -13159,9 +14311,13 @@ var BackgroundReindexer = class {
   stop() {
     this.stopped = true;
     this.pending = false;
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
   }
   drain() {
-    if (this.stopped || this.running || !this.pending) {
+    if (this.stopped || this.running || this.retryTimer || !this.pending) {
       return;
     }
     this.pending = false;
@@ -13169,13 +14325,29 @@ var BackgroundReindexer = class {
     void this.run();
   }
   async run() {
+    let retryAfterContention = false;
     try {
       await this.runIndex();
+      this.retryDelayMs = 50;
     } catch (error) {
-      console.error("[codebase-index] Background reindex failed:", error);
+      if (isTransientIndexLockContention(error)) {
+        this.pending = true;
+        retryAfterContention = true;
+      } else {
+        console.error("[codebase-index] Background reindex failed:", error);
+      }
     } finally {
       this.running = false;
-      this.drain();
+      if (retryAfterContention && !this.stopped) {
+        const delay = this.retryDelayMs;
+        this.retryDelayMs = Math.min(this.retryDelayMs * 2, 500);
+        this.retryTimer = setTimeout(() => {
+          this.retryTimer = null;
+          this.drain();
+        }, delay);
+      } else {
+        this.drain();
+      }
     }
   }
 };
@@ -13209,10 +14381,12 @@ function createWatcherWithIndexer(getIndexer, projectRoot, config, host = "openc
   return {
     fileWatcher,
     gitWatcher,
-    stop() {
+    whenReady() {
+      return fileWatcher.waitUntilReady();
+    },
+    async stop() {
       backgroundReindexer.stop();
-      fileWatcher.stop();
-      gitWatcher?.stop();
+      await Promise.all([fileWatcher.stop(), gitWatcher?.stop()]);
     }
   };
 }
@@ -13231,7 +14405,7 @@ function getConfigPaths(projectRoot, host, options) {
 
 // src/tools/visualize/activity.ts
 import { execFileSync } from "child_process";
-import * as path23 from "path";
+import * as path24 from "path";
 function attachRecentActivity(data, projectRoot) {
   const activity = readGitActivity(projectRoot);
   const changes = activity.size > 0 ? buildGitChanges(data, activity, projectRoot) : buildGraphChanges(data);
@@ -13393,7 +14567,7 @@ function normalizePath3(filePath) {
   return filePath.replace(/\\/g, "/");
 }
 function toGitRelativePath(projectRoot, filePath) {
-  const relativePath = path23.isAbsolute(filePath) ? path23.relative(projectRoot, filePath) : filePath;
+  const relativePath = path24.isAbsolute(filePath) ? path24.relative(projectRoot, filePath) : filePath;
   return normalizePath3(relativePath);
 }
 
@@ -13651,7 +14825,7 @@ render();
 }
 
 // src/tools/visualize/transform.ts
-import * as path24 from "path";
+import * as path25 from "path";
 
 // src/tools/visualize/modules.ts
 var MAX_MODULES = 18;
@@ -13911,7 +15085,7 @@ function transformForVisualization(symbols, edges, options = {}) {
     filePath: s.filePath,
     kind: s.kind,
     line: s.startLine,
-    directory: path24.dirname(s.filePath),
+    directory: path25.dirname(s.filePath),
     moduleId: "",
     moduleLabel: ""
   }));
@@ -13939,9 +15113,9 @@ function parseArgs(argv) {
   let host = "opencode";
   for (let i = 2; i < argv.length; i++) {
     if (argv[i] === "--project" && argv[i + 1]) {
-      project = path25.resolve(argv[++i]);
+      project = path26.resolve(argv[++i]);
     } else if (argv[i] === "--config" && argv[i + 1]) {
-      config = path25.resolve(argv[++i]);
+      config = path26.resolve(argv[++i]);
     } else if (argv[i] === "--host" && argv[i + 1]) {
       host = parseHostMode(argv[++i]);
     } else if (argv[i] === "--host") {
@@ -13954,7 +15128,7 @@ function loadCliRawConfig(args) {
   return args.config ? loadConfigFile(args.config) : loadMergedConfig(args.project, args.host);
 }
 function isCliEntrypoint(moduleUrl, argvPath) {
-  return argvPath !== void 0 && realpathSync2(fileURLToPath2(moduleUrl)) === realpathSync2(argvPath);
+  return argvPath !== void 0 && realpathSync3(fileURLToPath2(moduleUrl)) === realpathSync3(argvPath);
 }
 function parseVisualizeArgs(argv, cwd) {
   let project = cwd;
@@ -13964,7 +15138,7 @@ function parseVisualizeArgs(argv, cwd) {
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--project" && argv[i + 1]) {
-      project = path25.resolve(argv[++i]);
+      project = path26.resolve(argv[++i]);
     } else if (arg === "--max" && argv[i + 1]) {
       maxNodes = Number(argv[++i]);
     } else if (arg.startsWith("--max=") || arg.startsWith("max=")) {
@@ -14001,8 +15175,8 @@ async function handleVisualizeCommand(argv, cwd) {
       console.error("No connected symbols found. Retry with: npm run visualize -- orphans");
       return 1;
     }
-    const outputPath = path25.join(os5.tmpdir(), `call-graph-${Date.now()}.html`);
-    writeFileSync6(outputPath, generateVisualizationHtml(vizData), "utf-8");
+    const outputPath = path26.join(os6.tmpdir(), `call-graph-${Date.now()}.html`);
+    writeFileSync7(outputPath, generateVisualizationHtml(vizData), "utf-8");
     console.log(`Temporal call graph visualization generated: ${outputPath}`);
     console.log(`Nodes: ${vizData.nodes.length} | Edges: ${vizData.edges.length}`);
     console.log(`Recent change lenses: ${vizData.changes?.length ?? 0}`);
@@ -14031,7 +15205,7 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   let watcher = null;
-  const isHomeDir = path25.resolve(args.project) === path25.resolve(os5.homedir());
+  const isHomeDir = path26.resolve(args.project) === path26.resolve(os6.homedir());
   const isValidProject = !isHomeDir && (!config.indexing.requireProjectMarker || hasProjectMarker(args.project));
   if (config.indexing.autoIndex && isValidProject) {
     const indexer = getIndexerForProject(args.project, args.host);
@@ -14046,14 +15220,25 @@ async function main() {
       args.config ? { configPath: args.config } : {}
     );
   }
-  const shutdown = () => {
-    watcher?.stop();
-    server.close().catch(() => {
-    });
-    process.exit(0);
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    try {
+      await watcher?.stop();
+      await server.close();
+      process.exit(0);
+    } catch (error) {
+      console.error("Failed to stop MCP server cleanly:", error);
+      process.exit(1);
+    }
   };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", () => {
+    void shutdown();
+  });
+  process.on("SIGTERM", () => {
+    void shutdown();
+  });
 }
 function handleMainError(error) {
   if (error instanceof Error && error.message.startsWith("Invalid host mode")) {