opencode-codebase-index 0.14.0 → 0.16.0

package/dist/pi-extension.js

@@ -490,7 +490,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(path16, checkUnignored, mode) {
+      test(path17, checkUnignored, mode) {
         let ignored = false;
         let unignored = false;
         let matchedRule;
@@ -499,7 +499,7 @@ var require_ignore = __commonJS({
           if (unignored === negative && ignored !== unignored || negative && !ignored && !unignored && !checkUnignored) {
             return;
           }
-          const matched = rule[mode].test(path16);
+          const matched = rule[mode].test(path17);
           if (!matched) {
             return;
           }
@@ -520,17 +520,17 @@ var require_ignore = __commonJS({
     var throwError = (message, Ctor) => {
       throw new Ctor(message);
     };
-    var checkPath = (path16, originalPath, doThrow) => {
-      if (!isString(path16)) {
+    var checkPath = (path17, originalPath, doThrow) => {
+      if (!isString(path17)) {
         return doThrow(
           `path must be a string, but got \`${originalPath}\``,
           TypeError
         );
       }
-      if (!path16) {
+      if (!path17) {
         return doThrow(`path must not be empty`, TypeError);
       }
-      if (checkPath.isNotRelative(path16)) {
+      if (checkPath.isNotRelative(path17)) {
         const r = "`path.relative()`d";
         return doThrow(
           `path should be a ${r} string, but got "${originalPath}"`,
@@ -539,7 +539,7 @@ var require_ignore = __commonJS({
       }
       return true;
     };
-    var isNotRelative = (path16) => REGEX_TEST_INVALID_PATH.test(path16);
+    var isNotRelative = (path17) => REGEX_TEST_INVALID_PATH.test(path17);
     checkPath.isNotRelative = isNotRelative;
     checkPath.convert = (p) => p;
     var Ignore2 = class {
@@ -569,19 +569,19 @@ var require_ignore = __commonJS({
       }
       // @returns {TestResult}
       _test(originalPath, cache, checkUnignored, slices) {
-        const path16 = originalPath && checkPath.convert(originalPath);
+        const path17 = originalPath && checkPath.convert(originalPath);
         checkPath(
-          path16,
+          path17,
           originalPath,
           this._strictPathCheck ? throwError : RETURN_FALSE
         );
-        return this._t(path16, cache, checkUnignored, slices);
+        return this._t(path17, cache, checkUnignored, slices);
       }
-      checkIgnore(path16) {
-        if (!REGEX_TEST_TRAILING_SLASH.test(path16)) {
-          return this.test(path16);
+      checkIgnore(path17) {
+        if (!REGEX_TEST_TRAILING_SLASH.test(path17)) {
+          return this.test(path17);
         }
-        const slices = path16.split(SLASH).filter(Boolean);
+        const slices = path17.split(SLASH).filter(Boolean);
         slices.pop();
         if (slices.length) {
           const parent = this._t(
@@ -594,18 +594,18 @@ var require_ignore = __commonJS({
             return parent;
           }
         }
-        return this._rules.test(path16, false, MODE_CHECK_IGNORE);
+        return this._rules.test(path17, false, MODE_CHECK_IGNORE);
       }
-      _t(path16, cache, checkUnignored, slices) {
-        if (path16 in cache) {
-          return cache[path16];
+      _t(path17, cache, checkUnignored, slices) {
+        if (path17 in cache) {
+          return cache[path17];
         }
         if (!slices) {
-          slices = path16.split(SLASH).filter(Boolean);
+          slices = path17.split(SLASH).filter(Boolean);
         }
         slices.pop();
         if (!slices.length) {
-          return cache[path16] = this._rules.test(path16, checkUnignored, MODE_IGNORE);
+          return cache[path17] = this._rules.test(path17, checkUnignored, MODE_IGNORE);
         }
         const parent = this._t(
           slices.join(SLASH) + SLASH,
@@ -613,29 +613,29 @@ var require_ignore = __commonJS({
           checkUnignored,
           slices
         );
-        return cache[path16] = parent.ignored ? parent : this._rules.test(path16, checkUnignored, MODE_IGNORE);
+        return cache[path17] = parent.ignored ? parent : this._rules.test(path17, checkUnignored, MODE_IGNORE);
       }
-      ignores(path16) {
-        return this._test(path16, this._ignoreCache, false).ignored;
+      ignores(path17) {
+        return this._test(path17, this._ignoreCache, false).ignored;
       }
       createFilter() {
-        return (path16) => !this.ignores(path16);
+        return (path17) => !this.ignores(path17);
       }
       filter(paths) {
         return makeArray(paths).filter(this.createFilter());
       }
       // @returns {TestResult}
-      test(path16) {
-        return this._test(path16, this._testCache, true);
+      test(path17) {
+        return this._test(path17, this._testCache, true);
       }
     };
     var factory = (options) => new Ignore2(options);
-    var isPathValid = (path16) => checkPath(path16 && checkPath.convert(path16), path16, RETURN_FALSE);
+    var isPathValid = (path17) => checkPath(path17 && checkPath.convert(path17), path17, 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 = (path16) => REGEX_TEST_WINDOWS_PATH_ABSOLUTE.test(path16) || isNotRelative(path16);
+      checkPath.isNotRelative = (path17) => REGEX_TEST_WINDOWS_PATH_ABSOLUTE.test(path17) || isNotRelative(path17);
     };
     if (
       // Detect `process` so that it can run in browsers.
@@ -655,10 +655,10 @@ import { Type as Type2 } from "typebox";
 
 // 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}",
@@ -1327,8 +1327,8 @@ function formatPrImpact(result) {
 }
 
 // src/tools/operations.ts
-import { existsSync as existsSync9, realpathSync, statSync as statSync3 } from "fs";
-import * as path15 from "path";
+import { existsSync as existsSync10, realpathSync as realpathSync2, statSync as statSync4 } from "fs";
+import * as path16 from "path";
 
 // src/config/merger.ts
 import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
@@ -1525,6 +1525,9 @@ function getHostProjectIndexRelativePath(host) {
 function hasHostProjectConfig(projectRoot3, host) {
   return existsSync4(path4.join(projectRoot3, getProjectConfigRelativePath(host)));
 }
+function hasHostGlobalConfig(host) {
+  return existsSync4(getGlobalConfigPath(host));
+}
 function getGlobalIndexPath(host = "opencode") {
   switch (host) {
     case "opencode":
@@ -1564,6 +1567,9 @@ function resolveGlobalIndexPath(host = "opencode") {
     return hostIndexPath;
   }
   if (host !== "opencode") {
+    if (hasHostGlobalConfig(host)) {
+      return hostIndexPath;
+    }
     const legacyIndexPath = getGlobalIndexPath("opencode");
     if (existsSync4(legacyIndexPath)) {
       return legacyIndexPath;
@@ -1829,8 +1835,8 @@ function loadMergedConfig(projectRoot3, host = "opencode") {
 }
 
 // src/indexer/index.ts
-import { existsSync as existsSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync2, renameSync, unlinkSync, mkdirSync as mkdirSync2, promises as fsPromises2 } from "fs";
-import * as path12 from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync7, statSync as statSync3, writeFileSync as writeFileSync3, renameSync as renameSync2, unlinkSync, mkdirSync as mkdirSync3, promises as fsPromises2 } from "fs";
+import * as path13 from "path";
 import { performance as performance2 } from "perf_hooks";
 import { execFile as execFile3 } from "child_process";
 import { promisify as promisify3 } from "util";
@@ -2937,17 +2943,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 };
 }
@@ -3984,6 +3990,12 @@ function createMockNativeBinding() {
       constructor() {
         throw error;
       }
+      static openReadOnly() {
+        throw error;
+      }
+      static createEmptyReadOnly() {
+        throw error;
+      }
       close() {
         throw error;
       }
@@ -4087,6 +4099,12 @@ var VectorStore = class {
   load() {
     this.inner.load();
   }
+  loadStrict() {
+    this.inner.loadStrict();
+  }
+  hasFingerprint() {
+    return this.inner.hasFingerprint();
+  }
   count() {
     return this.inner.count();
   }
@@ -4369,12 +4387,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");
@@ -4803,6 +4833,428 @@ async function getChunkGitBlame(projectRoot3, filePath, startLine, endLine) {
   }
 }
 
+// src/indexer/index-lock.ts
+import { randomUUID } from "crypto";
+import {
+  existsSync as existsSync7,
+  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 path12 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(path12.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(path12.join(candidatePath, OWNER_FILE_NAME), JSON.stringify(value), {
+      encoding: "utf-8",
+      flag: "wx",
+      mode: 384
+    });
+    if (existsSync7(finalPath)) return false;
+    try {
+      renameSync(candidatePath, finalPath);
+      return true;
+    } catch (error) {
+      if (existsSync7(finalPath)) return false;
+      throw error;
+    }
+  } finally {
+    if (existsSync7(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 path12.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 = path12.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(path12.join(indexPath, entry), { recursive: true, force: true });
+  }
+}
+function removeDeadReclaimMarker(lockPath, expectedOwner) {
+  const markerPath = path12.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 (!existsSync7(markerPath) && existsSync7(claimedMarkerPath)) {
+      renameSync(claimedMarkerPath, markerPath);
+    }
+    return false;
+  }
+  rmSync(claimedMarkerPath, { recursive: true, force: true });
+  return true;
+}
+function reclaimDeadOwner(indexPath, lockPath, expectedOwner) {
+  const reclaimPath = path12.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 acquireIndexLock(indexPath, operation) {
+  mkdirSync2(indexPath, { recursive: true });
+  const canonicalIndexPath = realpathSync.native(indexPath);
+  const lockPath = path12.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 (!existsSync7(lease.lockPath) && existsSync7(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 (existsSync7(temporaryPath)) rmSync(temporaryPath, { recursive: true, force: true });
+}
+function recoverLeaseArtifacts(indexPath, owner, backupTargets) {
+  for (const targetPath of backupTargets) {
+    const backupPath = createLeaseTemporaryPath(targetPath, owner, "bak");
+    if (!existsSync7(backupPath)) continue;
+    if (existsSync7(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(path12.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"]);
@@ -4884,6 +5336,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 {};
@@ -5081,9 +5534,9 @@ function hasAllEmbeddingParts(parts, expectedPartCount) {
   return true;
 }
 function isPathWithinRoot(filePath, rootPath) {
-  const normalizedFilePath = path12.resolve(filePath);
-  const normalizedRoot = path12.resolve(rootPath);
-  return normalizedFilePath === normalizedRoot || normalizedFilePath.startsWith(`${normalizedRoot}${path12.sep}`);
+  const normalizedFilePath = path13.resolve(filePath);
+  const normalizedRoot = path13.resolve(rootPath);
+  return normalizedFilePath === normalizedRoot || normalizedFilePath.startsWith(`${normalizedRoot}${path13.sep}`);
 }
 var rankingQueryTokenCache = /* @__PURE__ */ new Map();
 var rankingNameTokenCache = /* @__PURE__ */ new Map();
@@ -6149,26 +6602,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(projectRoot3, config, host = "opencode") {
     this.projectRoot = projectRoot3;
     this.config = config;
     this.host = host;
     this.indexPath = this.getIndexPath();
-    this.fileHashCachePath = path12.join(this.indexPath, "file-hashes.json");
-    this.failedBatchesPath = path12.join(this.indexPath, "failed-batches.json");
-    this.indexingLockPath = path12.join(this.indexPath, "indexing.lock");
+    this.fileHashCachePath = path13.join(this.indexPath, "file-hashes.json");
+    this.failedBatchesPath = path13.join(this.indexPath, "failed-batches.json");
     this.logger = initializeLogger(config.debug);
   }
   getIndexPath() {
     return resolveProjectIndexPath(this.projectRoot, this.config.scope, this.host);
   }
+  isLocalProjectIndexPath() {
+    const localProjectIndexPaths = [path13.join(this.projectRoot, getHostProjectIndexRelativePath(this.host))];
+    if (this.host !== "opencode") {
+      localProjectIndexPaths.push(path13.join(this.projectRoot, getHostProjectIndexRelativePath("opencode")));
+    }
+    return localProjectIndexPaths.some((localPath) => {
+      if (!existsSync8(localPath) || !existsSync8(this.indexPath)) {
+        return path13.resolve(this.indexPath) === path13.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 = path13.join(this.indexPath, "file-hashes.json");
+    this.failedBatchesPath = path13.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 (!existsSync8(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 (!existsSync7(this.fileHashCachePath)) {
+    if (!existsSync8(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) {
@@ -6188,15 +6748,26 @@ var Indexer = class {
     this.atomicWriteSync(this.fileHashCachePath, JSON.stringify(obj));
   }
   atomicWriteSync(targetPath, data) {
-    const tempPath = `${targetPath}.tmp`;
-    mkdirSync2(path12.dirname(targetPath), { recursive: true });
-    writeFileSync2(tempPath, data);
-    renameSync(tempPath, targetPath);
+    const lease = this.requireActiveLease();
+    const tempPath = createLeaseTemporaryPath(targetPath, lease.owner, "tmp");
+    mkdirSync3(path13.dirname(targetPath), { recursive: true });
+    try {
+      writeFileSync3(tempPath, data);
+      renameSync2(tempPath, targetPath);
+    } finally {
+      removeLeaseTemporaryPath(tempPath);
+    }
+  }
+  saveInvertedIndex(invertedIndex) {
+    this.atomicWriteSync(
+      path13.join(this.indexPath, "inverted-index.json"),
+      invertedIndex.serialize()
+    );
   }
   getScopedRoots() {
-    const roots = /* @__PURE__ */ new Set([path12.resolve(this.projectRoot)]);
+    const roots = /* @__PURE__ */ new Set([path13.resolve(this.projectRoot)]);
     for (const kbRoot of this.config.knowledgeBases) {
-      roots.add(path12.resolve(this.projectRoot, kbRoot));
+      roots.add(path13.resolve(this.projectRoot, kbRoot));
     }
     return Array.from(roots);
   }
@@ -6205,29 +6776,29 @@ var Indexer = class {
     if (this.config.scope !== "global") {
       return branchName;
     }
-    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path13.resolve(this.projectRoot)).slice(0, 16);
     return `${projectHash}:${branchName}`;
   }
   getBranchCatalogKeyFor(branchName) {
     if (this.config.scope !== "global") {
       return branchName;
     }
-    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path13.resolve(this.projectRoot)).slice(0, 16);
     return `${projectHash}:${branchName}`;
   }
   getLegacyBranchCatalogKey() {
     return this.currentBranch || "default";
   }
   getLegacyMigrationMetadataKey() {
-    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path13.resolve(this.projectRoot)).slice(0, 16);
     return `index.globalBranchMigration.${projectHash}`;
   }
   getProjectEmbeddingStrategyMetadataKey() {
-    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path13.resolve(this.projectRoot)).slice(0, 16);
     return `index.embeddingStrategyVersion.${projectHash}`;
   }
   getProjectForceReembedMetadataKey() {
-    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path13.resolve(this.projectRoot)).slice(0, 16);
     return `index.forceReembed.${projectHash}`;
   }
   hasProjectForceReembedPending() {
@@ -6321,7 +6892,7 @@ var Indexer = class {
     if (!this.database) {
       return { chunkIds, symbolIds };
     }
-    const projectRootPath = path12.resolve(this.projectRoot);
+    const projectRootPath = path13.resolve(this.projectRoot);
     const projectLocalFilePaths = /* @__PURE__ */ new Set([
       ...Array.from(this.fileHashCache.keys()).filter(
         (filePath) => this.isFileInCurrentScope(filePath, roots) && isPathWithinRoot(filePath, projectRootPath)
@@ -6344,7 +6915,7 @@ var Indexer = class {
     if (this.config.scope !== "global") {
       return this.getBranchCatalogCleanupKeys();
     }
-    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path13.resolve(this.projectRoot)).slice(0, 16);
     const keys = /* @__PURE__ */ new Set();
     const projectChunkIdSet = new Set(projectChunkIds);
     const projectSymbolIdSet = new Set(projectSymbolIds);
@@ -6428,7 +6999,7 @@ var Indexer = class {
     if (!this.database || this.config.scope !== "global") {
       return false;
     }
-    const projectHash = hashContent(path12.resolve(this.projectRoot)).slice(0, 16);
+    const projectHash = hashContent(path13.resolve(this.projectRoot)).slice(0, 16);
     const roots = this.getScopedRoots();
     const { chunkIds: projectLocalChunkIds, symbolIds: projectLocalSymbolIds } = this.getProjectLocalScopedOwnershipIds(roots);
     return this.database.getAllBranches().some(
@@ -6462,7 +7033,7 @@ var Indexer = class {
       ...Array.from(this.fileHashCache.keys()).filter((filePath) => this.isFileInCurrentScope(filePath, roots)),
       ...scopedEntries.map(({ metadata }) => metadata.filePath)
     ]);
-    const projectRootPath = path12.resolve(this.projectRoot);
+    const projectRootPath = path13.resolve(this.projectRoot);
     const projectLocalFilePaths = new Set(
       Array.from(filePaths).filter((filePath) => isPathWithinRoot(filePath, projectRootPath))
     );
@@ -6524,34 +7095,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 existsSync7(this.indexingLockPath);
-  }
-  acquireIndexingLock() {
-    const lockData = {
-      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      pid: process.pid
-    };
-    writeFileSync2(this.indexingLockPath, JSON.stringify(lockData));
-  }
-  releaseIndexingLock() {
-    if (existsSync7(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 (existsSync7(this.fileHashCachePath)) {
-      unlinkSync(this.fileHashCachePath);
+    if (this.config.scope === "global") {
+      if (existsSync8(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) {
@@ -6567,10 +7131,10 @@ var Indexer = class {
     }
   }
   loadSerializedFailedBatches() {
-    if (!existsSync7(this.failedBatchesPath)) {
+    if (!existsSync8(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 : [];
@@ -6587,7 +7151,7 @@ var Indexer = class {
   }
   saveFailedBatches(batches) {
     if (batches.length === 0) {
-      if (existsSync7(this.failedBatchesPath)) {
+      if (existsSync8(this.failedBatchesPath)) {
         try {
           unlinkSync(this.failedBatchesPath);
         } catch {
@@ -6595,7 +7159,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();
@@ -6789,6 +7353,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 = path13.join(this.indexPath, "vectors");
+    return {
+      vectors: `${this.getReaderFileFingerprint(storePath)}|${this.getReaderFileFingerprint(`${storePath}.meta.json`)}`,
+      keyword: this.getReaderFileFingerprint(path13.join(this.indexPath, "inverted-index.json")),
+      database: this.getReaderFileFingerprint(path13.join(this.indexPath, "codebase.db")),
+      databaseIdentity: this.getReaderFileFingerprint(path13.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 = path13.join(this.indexPath, "vectors");
+    const vectorMetadataPath = `${storePath}.meta.json`;
+    const invertedIndexPath = path13.join(this.indexPath, "inverted-index.json");
+    const dbPath = path13.join(this.indexPath, "codebase.db");
+    if (vectorsChanged || retryDue("vectors")) {
+      const vectorStoreExists = existsSync8(storePath);
+      const vectorMetadataExists = existsSync8(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") || !existsSync8(invertedIndexPath) && (this.store?.count() ?? 0) > 0) {
+      if (existsSync8(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 (existsSync8(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.");
@@ -6820,36 +7600,103 @@ var Indexer = class {
         });
       }
     }
-    await fsPromises2.mkdir(this.indexPath, { recursive: true });
     const dimensions = this.configuredProviderInfo.modelInfo.dimensions;
-    const storePath = path12.join(this.indexPath, "vectors");
-    this.store = new VectorStore(storePath, dimensions);
-    const indexFilePath = path12.join(this.indexPath, "vectors.usearch");
-    if (existsSync7(indexFilePath)) {
-      this.store.load();
-    }
-    const invertedIndexPath = path12.join(this.indexPath, "inverted-index.json");
-    this.invertedIndex = new InvertedIndex(invertedIndexPath);
-    try {
-      this.invertedIndex.load();
-    } catch {
-      if (existsSync7(invertedIndexPath)) {
-        await fsPromises2.unlink(invertedIndexPath);
+    const storePath = path13.join(this.indexPath, "vectors");
+    const vectorMetadataPath = `${storePath}.meta.json`;
+    const invertedIndexPath = path13.join(this.indexPath, "inverted-index.json");
+    const dbPath = path13.join(this.indexPath, "codebase.db");
+    let dbIsNew = !existsSync8(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 (existsSync8(storePath) || existsSync8(vectorMetadataPath)) {
+        this.store.load();
       }
       this.invertedIndex = new InvertedIndex(invertedIndexPath);
-    }
-    const dbPath = path12.join(this.indexPath, "codebase.db");
-    let dbIsNew = !existsSync7(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 (existsSync8(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 = existsSync8(storePath);
+      const vectorMetadataExists = existsSync8(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 (existsSync8(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 (existsSync8(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);
@@ -6863,10 +7710,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();
@@ -6878,9 +7725,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;
@@ -6897,7 +7746,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 {
@@ -6919,7 +7768,7 @@ var Indexer = class {
         if (await this.tryResetCorruptedIndex("running automatic orphan garbage collection", error)) {
           return {
             resetCorruptedIndex: true,
-            warning: this.getCorruptedIndexWarning(path12.join(this.indexPath, "codebase.db"))
+            warning: this.getCorruptedIndexWarning(path13.join(this.indexPath, "codebase.db"))
           };
         }
         throw error;
@@ -6934,28 +7783,29 @@ var Indexer = class {
       return;
     }
     const retainedEntries = store.getAllMetadata().filter(({ key }) => !excludedSet.has(key));
-    const storeBasePath = path12.join(this.indexPath, "vectors");
-    const storeIndexPath = `${storeBasePath}.usearch`;
+    const storeBasePath = path13.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 (existsSync7(backupIndexPath)) {
+    if (existsSync8(backupIndexPath)) {
       unlinkSync(backupIndexPath);
     }
-    if (existsSync7(backupMetadataPath)) {
+    if (existsSync8(backupMetadataPath)) {
       unlinkSync(backupMetadataPath);
     }
     try {
-      if (existsSync7(storeIndexPath)) {
-        renameSync(storeIndexPath, backupIndexPath);
+      if (existsSync8(storeIndexPath)) {
+        renameSync2(storeIndexPath, backupIndexPath);
         backedUpIndex = true;
       }
-      if (existsSync7(storeMetadataPath)) {
-        renameSync(storeMetadataPath, backupMetadataPath);
+      if (existsSync8(storeMetadataPath)) {
+        renameSync2(storeMetadataPath, backupMetadataPath);
         backedUpMetadata = true;
       }
       store.clear();
@@ -6975,10 +7825,10 @@ var Indexer = class {
         rebuiltCount += 1;
       }
       store.save();
-      if (backedUpIndex && existsSync7(backupIndexPath)) {
+      if (backedUpIndex && existsSync8(backupIndexPath)) {
         unlinkSync(backupIndexPath);
       }
-      if (backedUpMetadata && existsSync7(backupMetadataPath)) {
+      if (backedUpMetadata && existsSync8(backupMetadataPath)) {
         unlinkSync(backupMetadataPath);
       }
       this.logger.gc("info", "Rebuilt vector store to avoid native remove", {
@@ -6991,17 +7841,17 @@ var Indexer = class {
         store.clear();
       } catch {
       }
-      if (existsSync7(storeIndexPath)) {
+      if (existsSync8(storeIndexPath)) {
         unlinkSync(storeIndexPath);
       }
-      if (existsSync7(storeMetadataPath)) {
+      if (existsSync8(storeMetadataPath)) {
         unlinkSync(storeMetadataPath);
       }
-      if (backedUpIndex && existsSync7(backupIndexPath)) {
-        renameSync(backupIndexPath, storeIndexPath);
+      if (backedUpIndex && existsSync8(backupIndexPath)) {
+        renameSync2(backupIndexPath, storeIndexPath);
       }
-      if (backedUpMetadata && existsSync7(backupMetadataPath)) {
-        renameSync(backupMetadataPath, storeMetadataPath);
+      if (backedUpMetadata && existsSync8(backupMetadataPath)) {
+        renameSync2(backupMetadataPath, storeMetadataPath);
       }
       if (backedUpIndex || backedUpMetadata) {
         store.load();
@@ -7015,11 +7865,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 = [
+      path13.join(this.indexPath, "codebase.db"),
+      path13.join(this.indexPath, "codebase.db-shm"),
+      path13.join(this.indexPath, "codebase.db-wal"),
+      path13.join(this.indexPath, "vectors"),
+      path13.join(this.indexPath, "vectors.usearch"),
+      path13.join(this.indexPath, "vectors.meta.json"),
+      path13.join(this.indexPath, "inverted-index.json"),
+      path13.join(this.indexPath, "file-hashes.json"),
+      path13.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 = path12.join(this.indexPath, "codebase.db");
+    const dbPath = path13.join(this.indexPath, "codebase.db");
     const warning = this.getCorruptedIndexWarning(dbPath);
     const errorMessage = getErrorMessage2(error);
     if (this.config.scope === "global") {
@@ -7035,30 +7911,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 = [
-      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.usearch"),
-      path12.join(this.indexPath, "inverted-index.json"),
-      path12.join(this.indexPath, "file-hashes.json"),
-      path12.join(this.indexPath, "failed-batches.json"),
-      path12.join(this.indexPath, "indexing.lock"),
-      path12.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() {
@@ -7177,8 +8030,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,
@@ -7202,7 +8109,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";
@@ -7212,7 +8124,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();
@@ -7361,7 +8272,7 @@ var Indexer = class {
     for (const parsed of parsedFiles) {
       currentFilePaths.add(parsed.path);
       if (parsed.chunks.length === 0) {
-        const relativePath = path12.relative(this.projectRoot, parsed.path);
+        const relativePath = path13.relative(this.projectRoot, parsed.path);
         stats.parseFailures.push(relativePath);
       }
       let fileChunkCount = 0;
@@ -7561,7 +8472,9 @@ var Indexer = class {
       database.addChunksToBranchBatch(branchCatalogKey, Array.from(currentChunkIds));
       database.clearBranchSymbols(branchCatalogKey);
       database.addSymbolsToBranchBatch(branchCatalogKey, Array.from(allSymbolIds));
-      if (backfilledBlameMetadata) {
+      const vectorPath = path13.join(this.indexPath, "vectors");
+      const shouldFingerprintLegacyPair = !store.hasFingerprint() && existsSync8(vectorPath) && existsSync8(`${vectorPath}.meta.json`);
+      if (backfilledBlameMetadata || shouldFingerprintLegacyPair) {
         store.save();
       }
       if (scopedRoots) {
@@ -7582,7 +8495,6 @@ var Indexer = class {
         chunksProcessed: 0,
         totalChunks: 0
       });
-      this.releaseIndexingLock();
       return stats;
     }
     if (pendingChunks.length === 0) {
@@ -7591,7 +8503,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);
@@ -7610,7 +8522,6 @@ var Indexer = class {
         chunksProcessed: 0,
         totalChunks: 0
       });
-      this.releaseIndexingLock();
       return stats;
     }
     onProgress?.({
@@ -7841,7 +8752,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 {
@@ -7893,7 +8804,6 @@ var Indexer = class {
       chunksProcessed: stats.indexedChunks,
       totalChunks: pendingChunks.length
     });
-    this.releaseIndexingLock();
     return stats;
   }
   async getQueryEmbedding(query, provider) {
@@ -7959,8 +8869,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.`
@@ -7974,6 +8884,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;
@@ -7982,7 +8893,7 @@ var Indexer = class {
     this.logger.search("debug", "Starting search", {
       query,
       maxResults,
-      hybridWeight,
+      hybridWeight: effectiveHybridWeight,
       fusionStrategy,
       rrfK,
       rerankTopN,
@@ -7990,13 +8901,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")) {
@@ -8028,12 +8948,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, {
@@ -8133,8 +9054,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 [];
@@ -8152,24 +9072,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();
@@ -8196,7 +9146,7 @@ var Indexer = class {
         store.clear();
         store.save();
         invertedIndex.clear();
-        invertedIndex.save();
+        this.saveInvertedIndex(invertedIndex);
         this.fileHashCache.clear();
         this.saveFileHashCache();
         database.clearAllIndexedData();
@@ -8220,14 +9170,7 @@ var Indexer = class {
       this.indexCompatibility = compatibility;
       return;
     }
-    const localProjectIndexPaths = [path12.join(this.projectRoot, getHostProjectIndexRelativePath(this.host))];
-    if (this.host !== "opencode") {
-      localProjectIndexPaths.push(path12.join(this.projectRoot, getHostProjectIndexRelativePath("opencode")));
-    }
-    const isLocalProjectIndex = localProjectIndexPaths.some(
-      (localPath) => path12.resolve(this.indexPath) === path12.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."
       );
@@ -8235,7 +9178,7 @@ var Indexer = class {
     store.clear();
     store.save();
     invertedIndex.clear();
-    invertedIndex.save();
+    this.saveInvertedIndex(invertedIndex);
     this.fileHashCache.clear();
     this.saveFileHashCache();
     database.clearAllIndexedData();
@@ -8253,7 +9196,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();
@@ -8266,7 +9215,7 @@ var Indexer = class {
     const removedChunkKeys = [];
     const chunkKeysByRemovedFile = /* @__PURE__ */ new Map();
     for (const [filePath, chunkKeys] of filePathsToChunkKeys) {
-      if (!existsSync7(filePath)) {
+      if (!existsSync8(filePath)) {
         chunkKeysByRemovedFile.set(filePath, chunkKeys);
         for (const key of chunkKeys) {
           removedChunkKeys.push(key);
@@ -8291,7 +9240,7 @@ var Indexer = class {
     const removedCount = removedChunkKeys.length;
     if (removedCount > 0) {
       store.save();
-      invertedIndex.save();
+      this.saveInvertedIndex(invertedIndex);
     }
     let gcOrphanEmbeddings;
     let gcOrphanChunks;
@@ -8306,7 +9255,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: [],
@@ -8315,7 +9264,7 @@ var Indexer = class {
         gcOrphanSymbols: 0,
         gcOrphanCallEdges: 0,
         resetCorruptedIndex: true,
-        warning: this.getCorruptedIndexWarning(path12.join(this.indexPath, "codebase.db"))
+        warning: this.getCorruptedIndexWarning(path13.join(this.indexPath, "codebase.db"))
       };
     }
     this.logger.recordGc(removedCount, gcOrphanChunks, gcOrphanEmbeddings);
@@ -8328,7 +9277,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;
@@ -8492,7 +9447,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());
@@ -8520,15 +9475,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.`
@@ -8642,7 +9598,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()) {
@@ -8656,7 +9613,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()) {
@@ -8670,43 +9628,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 path16 = database.findShortestPath(fromName, toName, branchKey, maxDepth);
-      if (path16.length > 0 && (shortest.length === 0 || path16.length < shortest.length)) {
-        shortest = path16;
+      const path17 = database.findShortestPath(fromName, toName, branchKey, maxDepth);
+      if (path17.length > 0 && (shortest.length === 0 || path17.length < shortest.length)) {
+        shortest = path17;
       }
     }
     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,
@@ -8729,7 +9694,7 @@ var Indexer = class {
         "Run index_codebase first to build the call graph and symbol index for this branch."
       );
     }
-    const absoluteChangedFiles = changedFiles.map((f) => path12.resolve(this.projectRoot, f));
+    const absoluteChangedFiles = changedFiles.map((f) => path13.resolve(this.projectRoot, f));
     const directSymbols = database.getSymbolsForFiles(absoluteChangedFiles, branchKey);
     const directIds = directSymbols.map((s) => s.id);
     const direction = opts.direction ?? "both";
@@ -8812,7 +9777,7 @@ var Indexer = class {
               projectRoot: this.projectRoot,
               baseBranch: this.baseBranch
             });
-            const otherAbsolute = otherChanged.files.map((f) => path12.resolve(this.projectRoot, f));
+            const otherAbsolute = otherChanged.files.map((f) => path13.resolve(this.projectRoot, f));
             const otherBranchKey = this.getBranchCatalogKeyFor(openPr.headRefName);
             const otherSymbols = database.getSymbolsForFiles(otherAbsolute, otherBranchKey);
             const otherLabels = /* @__PURE__ */ new Set();
@@ -8862,7 +9827,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()) {
@@ -8875,12 +9841,12 @@ var Indexer = class {
         if (meta.filePath) filePaths.add(meta.filePath);
       }
       const directory = options?.directory?.replace(/\/$/, "");
-      const absoluteDirectoryFilter = directory ? path12.resolve(this.projectRoot, directory) : void 0;
+      const absoluteDirectoryFilter = directory ? path13.resolve(this.projectRoot, directory) : void 0;
       for (const filePath of filePaths) {
         if (directory) {
-          const absoluteFilePath = path12.resolve(filePath);
+          const absoluteFilePath = path13.resolve(filePath);
           const matchesRelative = filePath === directory || filePath.startsWith(directory + "/");
-          const matchesProjectRelative = absoluteDirectoryFilter !== void 0 && (absoluteFilePath === absoluteDirectoryFilter || absoluteFilePath.startsWith(absoluteDirectoryFilter + path12.sep));
+          const matchesProjectRelative = absoluteDirectoryFilter !== void 0 && (absoluteFilePath === absoluteDirectoryFilter || absoluteFilePath.startsWith(absoluteDirectoryFilter + path13.sep));
           if (!matchesRelative && !matchesProjectRelative) {
             continue;
           }
@@ -8902,53 +9868,64 @@ 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();
   }
 };
 
 // src/tools/knowledge-base-paths.ts
-import * as path13 from "path";
+import * as path14 from "path";
 function resolveConfigPathValue(value, baseDir) {
   const trimmed = value.trim();
   if (!trimmed) {
     return trimmed;
   }
-  const absolutePath = path13.isAbsolute(trimmed) ? trimmed : path13.resolve(baseDir, trimmed);
-  return path13.normalize(absolutePath);
+  const absolutePath = path14.isAbsolute(trimmed) ? trimmed : path14.resolve(baseDir, trimmed);
+  return path14.normalize(absolutePath);
 }
 function serializeConfigPathValue(value, baseDir) {
   const trimmed = value.trim();
   if (!trimmed) {
     return trimmed;
   }
-  if (!path13.isAbsolute(trimmed)) {
-    return normalizePathSeparators(path13.normalize(trimmed));
+  if (!path14.isAbsolute(trimmed)) {
+    return normalizePathSeparators(path14.normalize(trimmed));
   }
-  const relativePath = path13.relative(baseDir, trimmed);
-  if (!relativePath || !relativePath.startsWith("..") && !path13.isAbsolute(relativePath)) {
-    return normalizePathSeparators(path13.normalize(relativePath || "."));
+  const relativePath = path14.relative(baseDir, trimmed);
+  if (!relativePath || !relativePath.startsWith("..") && !path14.isAbsolute(relativePath)) {
+    return normalizePathSeparators(path14.normalize(relativePath || "."));
   }
-  return path13.normalize(trimmed);
+  return path14.normalize(trimmed);
 }
 function resolveKnowledgeBasePath(value, projectRoot3) {
-  return path13.isAbsolute(value) ? value : path13.resolve(projectRoot3, value);
+  return path14.isAbsolute(value) ? value : path14.resolve(projectRoot3, value);
 }
 function normalizeKnowledgeBasePath2(value, projectRoot3) {
-  return path13.normalize(resolveKnowledgeBasePath(value, projectRoot3));
+  return path14.normalize(resolveKnowledgeBasePath(value, projectRoot3));
 }
 function hasMatchingKnowledgeBasePath(knowledgeBases, inputPath, projectRoot3) {
-  const normalizedInput = path13.normalize(inputPath);
+  const normalizedInput = path14.normalize(inputPath);
   return knowledgeBases.some((kb) => normalizeKnowledgeBasePath2(kb, projectRoot3) === normalizedInput);
 }
 function findKnowledgeBasePathIndex(knowledgeBases, inputPath, projectRoot3) {
-  const normalizedInput = path13.normalize(inputPath);
+  const normalizedInput = path14.normalize(inputPath);
   return knowledgeBases.findIndex(
-    (kb) => path13.normalize(kb) === normalizedInput || normalizeKnowledgeBasePath2(kb, projectRoot3) === normalizedInput
+    (kb) => path14.normalize(kb) === normalizedInput || normalizeKnowledgeBasePath2(kb, projectRoot3) === normalizedInput
   );
 }
 
@@ -9048,6 +10025,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}`);
@@ -9093,6 +10074,17 @@ function calculatePercentage(progress) {
   if (progress.phase === "storing") return 95;
   return 0;
 }
+function formatCodebasePeek(results) {
+  if (results.length === 0) {
+    return "No matching code found. Try a different query or run index_codebase first.";
+  }
+  const formatted = results.map((r, idx) => {
+    const location = `${r.filePath}:${r.startLine}-${r.endLine}`;
+    const name = r.name ? `"${r.name}"` : "(anonymous)";
+    return `[${idx + 1}] ${r.chunkType} ${name} at ${location} (score: ${r.score.toFixed(2)})${formatBlame(r)}`;
+  });
+  return formatted.join("\n");
+}
 function formatHealthCheck(result) {
   if (result.resetCorruptedIndex) {
     return result.warning ?? "Detected a corrupted local index and reset it. Run index_codebase to rebuild search data.";
@@ -9142,16 +10134,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, path16) {
-  if (path16.length === 0) {
+function formatCallGraphPath(from, to, path17) {
+  if (path17.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 = path16.map((hop, index) => {
+  const formatted = path17.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 (${path16.length} hops):
+  return `Path (${path17.length} hops):
 ${formatted.join("\n")}`;
 }
 function formatResultHeader(result, index) {
@@ -9191,8 +10183,8 @@ ${truncateContent(r.content)}
 }
 
 // src/tools/config-state.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
-import * as path14 from "path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
+import * as path15 from "path";
 function normalizeKnowledgeBasePaths(config, projectRoot3) {
   const normalized = { ...config };
   if (Array.isArray(normalized.knowledgeBases)) {
@@ -9219,10 +10211,10 @@ function loadEditableConfig(projectRoot3, host = "opencode") {
 }
 function saveConfig(projectRoot3, config, host = "opencode") {
   const configPath = getConfigPath(projectRoot3, host);
-  const configDir = path14.dirname(configPath);
-  const configBaseDir = path14.dirname(configDir);
-  if (!existsSync8(configDir)) {
-    mkdirSync3(configDir, { recursive: true });
+  const configDir = path15.dirname(configPath);
+  const configBaseDir = path15.dirname(configDir);
+  if (!existsSync9(configDir)) {
+    mkdirSync4(configDir, { recursive: true });
   }
   const serializableConfig = { ...config };
   if (Array.isArray(serializableConfig.knowledgeBases)) {
@@ -9230,13 +10222,31 @@ function saveConfig(projectRoot3, config, host = "opencode") {
       (kb) => serializeConfigPathValue(kb, configBaseDir)
     );
   }
-  writeFileSync3(configPath, JSON.stringify(serializableConfig, null, 2) + "\n", "utf-8");
+  writeFileSync4(configPath, JSON.stringify(serializableConfig, null, 2) + "\n", "utf-8");
 }
 
 // src/tools/operations.ts
 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(projectRoot3, host) {
   if (projectRoot3) {
     return projectRoot3;
@@ -9274,8 +10284,8 @@ function refreshIndexerForDirectory(projectRoot3, host = "opencode", config = pa
 }
 function shouldForceLocalizeProjectIndex(projectRoot3, host = "opencode") {
   const root = getProjectRoot(projectRoot3, host);
-  const localIndexPath = path15.join(root, getHostProjectIndexRelativePath(host));
-  if (existsSync9(localIndexPath)) {
+  const localIndexPath = path16.join(root, getHostProjectIndexRelativePath(host));
+  if (existsSync10(localIndexPath)) {
     return false;
   }
   const inheritedIndexPath = resolveWorktreeFallbackProjectIndexPath(root, host);
@@ -9331,35 +10341,46 @@ async function getCallGraphPath(projectRoot3, host, from, to, maxDepth) {
 async function runIndexCodebase(projectRoot3, host, args, onProgress) {
   const root = getProjectRoot(projectRoot3, 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(projectRoot3, host) {
   const indexer = getIndexerForProject(projectRoot3, host);
@@ -9369,6 +10390,15 @@ async function getIndexHealthCheck(projectRoot3, host) {
   const indexer = getIndexerForProject(projectRoot3, host);
   return indexer.healthCheck();
 }
+async function runIndexHealthCheck(projectRoot3, host) {
+  try {
+    return { kind: "health", health: await getIndexHealthCheck(projectRoot3, host) };
+  } catch (error) {
+    const busyResult = getIndexBusyResult(error);
+    if (!busyResult) throw error;
+    return busyResult;
+  }
+}
 async function getPrImpact(projectRoot3, host, params) {
   const indexer = getIndexerForProject(projectRoot3, host);
   return indexer.getPrImpact({
@@ -9435,15 +10465,15 @@ async function getIndexLogs(projectRoot3, host, args) {
 function addKnowledgeBase(projectRoot3, host, knowledgeBasePath) {
   const root = getProjectRoot(projectRoot3, host);
   const inputPath = knowledgeBasePath.trim();
-  const normalizedPath = path15.resolve(
-    path15.isAbsolute(inputPath) ? inputPath : resolveKnowledgeBasePath(inputPath, root)
+  const normalizedPath = path16.resolve(
+    path16.isAbsolute(inputPath) ? inputPath : resolveKnowledgeBasePath(inputPath, root)
   );
-  if (!existsSync9(normalizedPath)) {
+  if (!existsSync10(normalizedPath)) {
     return `Error: Directory does not exist: ${normalizedPath}`;
   }
   let realPath;
   try {
-    realPath = realpathSync(normalizedPath);
+    realPath = realpathSync2(normalizedPath);
   } catch {
     return `Error: Cannot resolve path: ${normalizedPath}`;
   }
@@ -9472,13 +10502,13 @@ function addKnowledgeBase(projectRoot3, host, knowledgeBasePath) {
     }
   }
   for (const dotDir of sensitiveDotDirs) {
-    const sensitiveDir = path15.join(homeDir, dotDir);
+    const sensitiveDir = path16.join(homeDir, dotDir);
     if (sensitiveDir && (realPath === sensitiveDir || realPath.startsWith(`${sensitiveDir}/`))) {
       return `Error: Adding sensitive directory as knowledge base is not allowed: ${normalizedPath}`;
     }
   }
   try {
-    const stat = statSync3(normalizedPath);
+    const stat = statSync4(normalizedPath);
     if (!stat.isDirectory()) {
       return `Error: Path is not a directory: ${normalizedPath}`;
     }
@@ -9518,7 +10548,7 @@ function listKnowledgeBases(projectRoot3, host) {
   for (let i = 0; i < knowledgeBases.length; i++) {
     const kb = knowledgeBases[i];
     const resolvedPath = resolveKnowledgeBasePath(kb, root);
-    const exists = existsSync9(resolvedPath);
+    const exists = existsSync10(resolvedPath);
     result += `[${i + 1}] ${kb}
 `;
     result += `    Resolved: ${resolvedPath}
@@ -9527,7 +10557,7 @@ function listKnowledgeBases(projectRoot3, host) {
 `;
     if (exists) {
       try {
-        const stat = statSync3(resolvedPath);
+        const stat = statSync4(resolvedPath);
         result += `    Type: ${stat.isDirectory() ? "Directory" : "File"}
 `;
       } catch {
@@ -9535,7 +10565,7 @@ function listKnowledgeBases(projectRoot3, host) {
     }
     result += "\n";
   }
-  const hasHostConfig = existsSync9(path15.join(root, getHostProjectConfigRelativePath(host)));
+  const hasHostConfig = existsSync10(path16.join(root, getHostProjectConfigRelativePath(host)));
   if (hasHostConfig) {
     result += `
 Config sources: 1 file(s).`;
@@ -9641,10 +10671,67 @@ function projectRoot2(ctx) {
   return ctx?.cwd ?? process.cwd();
 }
 function codebaseIndexPiExtension(pi) {
+  pi.registerTool({
+    name: "codebase_context",
+    label: "Codebase Context",
+    description: "PREFERRED FIRST TOOL for any repository question. Check index_status when freshness is unknown, then use this tool for low-token location discovery and dependency flow.",
+    parameters: Type2.Object({
+      query: Type2.String({ description: "Natural language description of what code you're trying to locate" }),
+      from: Type2.Optional(Type2.String({ description: "Source symbol when asking for a dependency path." })),
+      to: Type2.Optional(Type2.String({ description: "Target symbol when asking for a dependency path." })),
+      symbol: Type2.Optional(Type2.String({ description: "Exact symbol name for an authoritative definition lookup." })),
+      limit: Type2.Optional(Type2.Number({ description: "Maximum results (default: 10)" })),
+      maxDepth: Type2.Optional(Type2.Number({ description: "Maximum call-graph traversal depth for from/to paths" })),
+      fileType: Type2.Optional(Type2.String({ description: "Filter by file extension, e.g., ts, py, rs" })),
+      directory: Type2.Optional(Type2.String({ description: "Filter by directory path" }))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const root = projectRoot2(ctx);
+      if (params.from && params.to) {
+        const path17 = await getCallGraphPath(root, HOST2, params.from, params.to, params.maxDepth);
+        if (path17.length > 0) {
+          return text2(formatCallGraphPath(params.from, params.to, path17), path17);
+        }
+        const { callers } = await getCallGraphData(root, HOST2, {
+          name: params.to,
+          direction: "callers"
+        });
+        const directEdge = callers.find((edge) => edge.fromSymbolName === params.from);
+        if (directEdge) {
+          const location = directEdge.fromSymbolFilePath ? ` at ${directEdge.fromSymbolFilePath}:${directEdge.line}` : "";
+          return text2(
+            `Direct path: ${params.from} --${directEdge.callType}--> ${params.to}${location} (edge is ${directEdge.isResolved ? "resolved" : "unresolved"}).`,
+            path17
+          );
+        }
+        return text2(formatCallGraphPath(params.from, params.to, path17), path17);
+      }
+      if (params.symbol) {
+        const results2 = await implementationLookup(root, HOST2, params.symbol, {
+          limit: params.limit ?? 10,
+          fileType: params.fileType,
+          directory: params.directory
+        });
+        return text2(formatDefinitionLookup(results2, params.symbol), results2);
+      }
+      const results = await searchCodebase(root, HOST2, params.query, {
+        limit: params.limit ?? 10,
+        fileType: params.fileType,
+        directory: params.directory,
+        metadataOnly: true
+      });
+      if (results.length === 0) {
+        return text2("No matching code found. Try a different query or run index_status/index_codebase first.");
+      }
+      return text2(`Found ${results.length} locations for "${params.query}":
+
+${formatCodebasePeek(results)}`, results);
+    }
+  });
   pi.registerTool({
     name: "codebase_search",
     label: "Codebase Search",
-    description: "Semantic search over the indexed codebase. Describe behavior, not syntax.",
+    description: "Use this after codebase_context when you need semantic content, not just locations. Describe behavior, not syntax.",
     parameters: Type2.Object({
       query: Type2.String({ description: "Natural language description of what code you're looking for" }),
       limit: Type2.Optional(Type2.Number({ description: "Maximum results (default: 10)" })),
@@ -9664,7 +10751,7 @@ function codebaseIndexPiExtension(pi) {
   pi.registerTool({
     name: "codebase_peek",
     label: "Codebase Peek",
-    description: "Semantic search returning only metadata (file, lines, symbol) to save tokens.",
+    description: "LOW-TOKEN location-first retrieval. Prefer codebase_context first, then use this for cheap conceptual lookup.",
     parameters: Type2.Object({
       query: Type2.String(),
       limit: Type2.Optional(Type2.Number()),
@@ -9683,7 +10770,7 @@ function codebaseIndexPiExtension(pi) {
   pi.registerTool({
     name: "find_similar",
     label: "Find Similar Code",
-    description: "Find code similar to a snippet for duplicate detection and pattern discovery.",
+    description: "Find code similar to a snippet for duplicate detection, pattern discovery, and refactor planning.",
     parameters: Type2.Object({
       code: Type2.String({ description: "Code snippet to compare" }),
       limit: Type2.Optional(Type2.Number()),
@@ -9700,7 +10787,7 @@ function codebaseIndexPiExtension(pi) {
   pi.registerTool({
     name: "implementation_lookup",
     label: "Implementation Lookup",
-    description: "Find likely symbol definitions or implementations by name or natural language.",
+    description: "Find likely symbol definitions or implementations after codebase_context identifies a symbol.",
     parameters: Type2.Object({
       query: Type2.String(),
       limit: Type2.Optional(Type2.Number()),
@@ -9715,7 +10802,7 @@ function codebaseIndexPiExtension(pi) {
   pi.registerTool({
     name: "index_codebase",
     label: "Index Codebase",
-    description: "Build or refresh the semantic codebase index.",
+    description: "Build or refresh the semantic codebase index. Run index_status when freshness is unknown.",
     parameters: Type2.Object({
       force: Type2.Optional(Type2.Boolean({ default: false })),
       estimateOnly: Type2.Optional(Type2.Boolean({ default: false })),
@@ -9723,7 +10810,9 @@ function codebaseIndexPiExtension(pi) {
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const result = await runIndexCodebase(projectRoot2(ctx), HOST2, params);
-      return result.kind === "estimate" ? text2(formatCostEstimate(result.estimate), result.estimate) : text2(formatIndexStats(result.stats, params.verbose ?? false), result.stats);
+      if (result.kind === "estimate") return text2(formatCostEstimate(result.estimate), result.estimate);
+      if (result.kind === "busy") return text2(result.text, { code: "INDEX_BUSY" });
+      return text2(formatIndexStats(result.stats, params.verbose ?? false), result.stats);
     }
   });
   pi.registerTool({
@@ -9739,11 +10828,12 @@ function codebaseIndexPiExtension(pi) {
   pi.registerTool({
     name: "index_health_check",
     label: "Index Health Check",
-    description: "Garbage collect orphaned embeddings/chunks and report health.",
+    description: "Garbage collect orphaned embeddings/chunks and report index health status.",
     parameters: Type2.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-      const result = await getIndexHealthCheck(projectRoot2(ctx), HOST2);
-      return text2(formatHealthCheck(result), result);
+      const result = await runIndexHealthCheck(projectRoot2(ctx), HOST2);
+      if (result.kind === "busy") return text2(result.text, { code: "INDEX_BUSY" });
+      return text2(formatHealthCheck(result.health), result.health);
     }
   });
   pi.registerTool({
@@ -9778,6 +10868,11 @@ function codebaseIndexPiExtension(pi) {
     }
   });
   registerPiCallGraphTools(pi);
+  pi.on("before_agent_start", (event) => ({
+    systemPrompt: `${event.systemPrompt}
+
+Check index_status first when index readiness is unknown. For repository questions, call codebase_context before search/grep/bash/read-style broad reads. Use implementation_lookup for known symbols and call_graph/call_graph_path after endpoints are identified for dependency flow. Avoid broad tool calls until semantic locations are known.`
+  }));
   pi.registerTool({
     name: "pr_impact",
     label: "PR Impact",