@wrongstack/tools 0.286.0 → 0.289.0

package/dist/codebase-index/index.js

@@ -92,7 +92,7 @@ import * as path from "node:path";
 import { resolveWstackPaths } from "@wrongstack/core";
 
 // src/codebase-index/schema.ts
-var SCHEMA_VERSION = 2;
+var SCHEMA_VERSION = 3;
 
 // src/codebase-index/lsp-kind.ts
 function lspKindToInternalKind(k) {
@@ -164,7 +164,7 @@ function tokenise(text) {
   return sanitised.toLowerCase().split(" ").filter(Boolean);
 }
 function splitName(name) {
-  return name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim();
+  return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([\p{L}])(\d)/gu, "$1 $2").replace(/(\d)([\p{L}])/gu, "$1 $2").replace(/[_-]+/g, " ").trim();
 }
 function buildIndexableText(name, signature, docComment) {
   return [splitName(name), name, signature, docComment].filter(Boolean).join(" ");
@@ -190,14 +190,12 @@ function buildBm25Index(docs) {
   return new Bm25Index(documents, df, N, avgLen);
 }
 var Bm25Index = class {
-  constructor(documents, df, N, avgLen) {
+  constructor(documents, _df, N, avgLen) {
     this.documents = documents;
-    this.df = df;
     this.N = N;
     this.safeAvgLen = avgLen === 0 ? 1 : avgLen;
   }
   documents;
-  df;
   N;
   safeAvgLen;
   score(query, filter) {
@@ -210,10 +208,13 @@ var Bm25Index = class {
       for (const qTerm of qTokens) {
         let tf = 0;
         for (const t of doc.tokens) {
-          if (t === qTerm) tf++;
+          if (t.startsWith(qTerm)) tf++;
         }
         if (tf === 0) continue;
-        const dfVal = this.df[qTerm] ?? 0;
+        let dfVal = 0;
+        for (const candidate of this.documents) {
+          if (candidate.tokens.some((t) => t.startsWith(qTerm))) dfVal++;
+        }
         if (dfVal === 0) continue;
         const idf = Math.log((this.N - dfVal + 0.5) / (dfVal + 0.5) + 1);
         const lenRatio = B * (doc.len / this.safeAvgLen);
@@ -246,6 +247,29 @@ var Bm25Index = class {
 
 // src/codebase-index/writer.ts
 var DB_FILE = "index.db";
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+function assignRefsToSymbols(refs, symbols) {
+  if (refs.length === 0 || symbols.length === 0) return [];
+  const ordered = [...symbols].sort((a, b) => a.line - b.line || a.col - b.col || a.id - b.id);
+  const seen = /* @__PURE__ */ new Set();
+  const assigned = [];
+  for (const ref of refs) {
+    let owner;
+    for (const symbol of ordered) {
+      if (symbol.line > ref.line) break;
+      owner = symbol;
+    }
+    if (!owner && ref.callType === "import") owner = ordered[0];
+    if (!owner || owner.id <= 0) continue;
+    const key = `${owner.id}:${ref.toName}:${ref.callType}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    assigned.push({ ...ref, fromId: owner.id });
+  }
+  return assigned;
+}
 function resolveIndexDir(projectRoot, override) {
   return override ?? resolveWstackPaths({ projectRoot }).projectCodebaseIndex;
 }
@@ -299,7 +323,7 @@ function sleepSync(ms) {
   } catch {
   }
 }
-var IndexStore = class {
+var IndexStore = class _IndexStore {
   db;
   /** Absolute path to this project's index directory. */
   indexDir;
@@ -351,10 +375,7 @@ var IndexStore = class {
           const msg = lastError instanceof Error ? lastError.message : String(lastError);
           throw new LockError(`SQLite lock conflict after ${MAX_LOCK_RETRIES} retries: ${msg}`);
         }
-        const delay = Math.min(
-          LOCK_RETRY_BASE_DELAY_MS * 2 ** attempt,
-          LOCK_RETRY_MAX_DELAY_MS
-        );
+        const delay = Math.min(LOCK_RETRY_BASE_DELAY_MS * 2 ** attempt, LOCK_RETRY_MAX_DELAY_MS);
         sleepSync(delay);
       }
     }
@@ -436,8 +457,24 @@ var IndexStore = class {
     this.db.exec("CREATE INDEX IF NOT EXISTS idx_r_to_name ON refs(to_name)");
     this.db.exec("CREATE INDEX IF NOT EXISTS idx_r_call_type ON refs(call_type)");
     try {
-      this.db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(text, tokenize = 'unicode61')");
+      this.db.exec(
+        "CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(text, tokenize = 'unicode61')"
+      );
       this.ftsAvailable = true;
+      const symbolCount = Number(
+        this.db.prepare("SELECT COUNT(*) AS n FROM symbols").get()?.n ?? 0
+      );
+      const ftsCount = Number(
+        this.db.prepare("SELECT COUNT(*) AS n FROM symbols_fts").get()?.n ?? 0
+      );
+      if (symbolCount !== ftsCount) {
+        this.db.exec("DELETE FROM symbols_fts");
+        const insert = this.db.prepare("INSERT INTO symbols_fts(rowid, text) VALUES (?, ?)");
+        const rows = this.db.prepare("SELECT id, name, signature, doc_comment FROM symbols ORDER BY id").all();
+        for (const row of rows) {
+          insert.run(row.id, buildIndexableText(row.name, row.signature, row.doc_comment));
+        }
+      }
     } catch {
       this.ftsAvailable = false;
     }
@@ -495,7 +532,9 @@ var IndexStore = class {
   deleteSymbolsForFile(file) {
     this.runWithRetry(() => {
       if (this.ftsAvailable) {
-        this.stmt("DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_fk = ?)").run(file);
+        this.stmt(
+          "DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_fk = ?)"
+        ).run(file);
       }
       this.stmt("DELETE FROM symbols WHERE file_fk = ?").run(file);
     });
@@ -507,9 +546,21 @@ var IndexStore = class {
    */
   deleteFile(file) {
     this.runWithRetry(() => {
-      this.deleteRefsForFile(file);
-      this.deleteSymbolsForFile(file);
-      this.stmt("DELETE FROM files WHERE file = ?").run(file);
+      this.db.exec("BEGIN IMMEDIATE");
+      try {
+        if (this.ftsAvailable) {
+          this.db.prepare(
+            "DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_fk = ?)"
+          ).run(file);
+        }
+        this.db.prepare("DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file_fk = ?)").run(file);
+        this.db.prepare("DELETE FROM symbols WHERE file_fk = ?").run(file);
+        this.db.prepare("DELETE FROM files WHERE file = ?").run(file);
+        this.db.exec("COMMIT");
+      } catch (err) {
+        this.db.exec("ROLLBACK");
+        throw err;
+      }
     });
   }
   // ─── File metadata ──────────────────────────────────────────────────────────
@@ -532,14 +583,22 @@ var IndexStore = class {
     ).all(file);
     if (!rows.length) return null;
     const r = expectDefined(rows[0]);
-    return { file: r.file, lang: r.lang, mtimeMs: r.mtime_ms, symbolCount: r.symbol_count, lastIndexed: r.last_indexed };
+    return {
+      file: r.file,
+      lang: r.lang,
+      mtimeMs: r.mtime_ms,
+      symbolCount: r.symbol_count,
+      lastIndexed: r.last_indexed
+    };
   }
   getAllFileMetas() {
-    return this.db.prepare(
-      "SELECT file, lang, mtime_ms, symbol_count, last_indexed FROM files"
-    ).all().map(
-      (r) => ({ file: r.file, lang: r.lang, mtimeMs: r.mtime_ms, symbolCount: r.symbol_count, lastIndexed: r.last_indexed })
-    );
+    return this.db.prepare("SELECT file, lang, mtime_ms, symbol_count, last_indexed FROM files").all().map((r) => ({
+      file: r.file,
+      lang: r.lang,
+      mtimeMs: r.mtime_ms,
+      symbolCount: r.symbol_count,
+      lastIndexed: r.last_indexed
+    }));
   }
   // ─── Search ──────────────────────────────────────────────────────────────────
   search(query, filter) {
@@ -563,8 +622,8 @@ var IndexStore = class {
       values.push(filter.lang);
     }
     if (filter?.file) {
-      conditions.push("file LIKE ?");
-      values.push(`%${filter.file}%`);
+      conditions.push("replace(file, '\\', '/') LIKE ? ESCAPE '\\'");
+      values.push(`%${escapeLike(filter.file.replace(/\\/g, "/"))}%`);
     }
     if (query.trim()) {
       const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
@@ -602,9 +661,11 @@ var IndexStore = class {
    * "users", camelCase-split text makes "complex" find "complexOperation").
    */
   searchRanked(query, filter, limit) {
+    const rawLimit = Number.isFinite(limit) ? Math.trunc(limit) : 20;
+    const safeLimit = Math.max(1, Math.min(rawLimit, 100));
     const tokens = tokenise(query);
     if (tokens.length === 0 || !this.ftsAvailable) {
-      return this.searchRankedFallback(query, filter, limit);
+      return this.searchRankedFallback(query, filter, safeLimit);
     }
     let effectiveKind = filter?.kind;
     if (filter?.lspKind !== void 0) {
@@ -624,11 +685,13 @@ var IndexStore = class {
       values.push(filter.lang);
     }
     if (filter?.file) {
-      conditions.push("s.file LIKE ?");
-      values.push(`%${filter.file}%`);
+      conditions.push("replace(s.file, '\\', '/') LIKE ? ESCAPE '\\'");
+      values.push(`%${escapeLike(filter.file.replace(/\\/g, "/"))}%`);
     }
     const where = conditions.join(" AND ");
-    const countRows = this.db.prepare(`SELECT COUNT(*) AS n FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE ${where}`).all(...values);
+    const countRows = this.db.prepare(
+      `SELECT COUNT(*) AS n FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE ${where}`
+    ).all(...values);
     const total = countRows[0] ? Number(countRows[0].n) : 0;
     if (total === 0) return { results: [], total: 0 };
     const rows = this.db.prepare(
@@ -637,9 +700,13 @@ var IndexStore = class {
                 snippet(symbols_fts, 0, '', '', '\u2026', 12) AS snippet
          FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid
          WHERE ${where}
-         ORDER BY bm25(symbols_fts)
+         ORDER BY
+           CASE WHEN lower(s.name) = lower(?) THEN 0
+                WHEN lower(s.name) LIKE lower(?) ESCAPE '\\' THEN 1
+                ELSE 2 END,
+           bm25(symbols_fts), lower(s.name), s.file, s.line, s.col, s.id
          LIMIT ?`
-    ).all(...values, limit);
+    ).all(...values, query.trim(), `${escapeLike(query.trim())}%`, safeLimit);
     return {
       results: rows.map((r) => ({
         id: r.id,
@@ -669,10 +736,28 @@ var IndexStore = class {
     }
     const candidateById = new Map(candidates.map((c) => [c.id, c]));
     const bm25 = buildBm25Index(
-      candidates.map((c) => ({ id: c.id, text: buildIndexableText(c.name, c.signature, c.docComment) }))
+      candidates.map((c) => ({
+        id: c.id,
+        text: buildIndexableText(c.name, c.signature, c.docComment)
+      }))
     );
     const scored = bm25.score(query, (id) => candidateById.has(id));
-    scored.sort((a, b) => b.score - a.score);
+    const q = query.trim().toLowerCase();
+    const rank = (id) => {
+      const name = candidateById.get(id)?.name.toLowerCase() ?? "";
+      if (name === q) return 0;
+      if (name.startsWith(q)) return 1;
+      return 2;
+    };
+    scored.sort((a, b) => {
+      const rankDiff = rank(a.id) - rank(b.id);
+      if (rankDiff !== 0) return rankDiff;
+      const scoreDiff = b.score - a.score;
+      if (scoreDiff !== 0) return scoreDiff;
+      const left = expectDefined(candidateById.get(a.id));
+      const right = expectDefined(candidateById.get(b.id));
+      return left.name.localeCompare(right.name) || left.file.localeCompare(right.file) || left.line - right.line || left.col - right.col || left.id - right.id;
+    });
     const qTokens = tokenise(query);
     const results = scored.slice(0, limit).map(({ id, score }) => {
       const c = expectDefined(candidateById.get(id));
@@ -681,9 +766,7 @@ var IndexStore = class {
     return { results, total: candidates.length };
   }
   getAllIndexable() {
-    return this.db.prepare("SELECT id, text FROM symbols").all().map(
-      ({ id, text }) => ({ id, text })
-    );
+    return this.db.prepare("SELECT id, text FROM symbols").all().map(({ id, text }) => ({ id, text }));
   }
   /**
    * Largest symbol id currently in the table (0 when empty). New ids must be
@@ -699,22 +782,16 @@ var IndexStore = class {
   // ─── Stats ───────────────────────────────────────────────────────────────────
   getStats() {
     const sizeBytes = this.sizeBytes();
-    const lastRows = this.db.prepare(
-      "SELECT value FROM metadata WHERE key = 'last_indexed'"
-    ).all();
+    const lastRows = this.db.prepare("SELECT value FROM metadata WHERE key = 'last_indexed'").all();
     const lastIndexed = lastRows.length ? Number(lastRows[0]?.value) : null;
     const totalRows = this.db.prepare("SELECT COUNT(*) FROM symbols").all();
     const totalSymbols = totalRows[0] ? Number(totalRows[0]["COUNT(*)"]) : 0;
     const fileRows = this.db.prepare("SELECT COUNT(*) FROM files").all();
     const totalFiles = fileRows[0] ? Number(fileRows[0]["COUNT(*)"]) : 0;
-    const langRows = this.db.prepare(
-      "SELECT lang, COUNT(*) FROM symbols GROUP BY lang"
-    ).all();
+    const langRows = this.db.prepare("SELECT lang, COUNT(*) FROM symbols GROUP BY lang").all();
     const byLang = {};
     for (const row of langRows) byLang[row.lang] = Number(row["COUNT(*)"]);
-    const kindRows = this.db.prepare(
-      "SELECT kind, COUNT(*) FROM symbols GROUP BY kind"
-    ).all();
+    const kindRows = this.db.prepare("SELECT kind, COUNT(*) FROM symbols GROUP BY kind").all();
     const byKind = {};
     for (const row of kindRows) byKind[row.kind] = Number(row["COUNT(*)"]);
     return {
@@ -730,17 +807,31 @@ var IndexStore = class {
   }
   setLastIndexed(ts2) {
     this.runWithRetry(() => {
-      this.db.prepare(
-        "INSERT OR REPLACE INTO metadata(key, value) VALUES('last_indexed', ?)"
-      ).run(String(ts2));
+      this.db.prepare("INSERT OR REPLACE INTO metadata(key, value) VALUES('last_indexed', ?)").run(String(ts2));
+    });
+  }
+  getMetadata(key) {
+    const rows = this.db.prepare("SELECT value FROM metadata WHERE key = ?").all(key);
+    return rows[0]?.value;
+  }
+  setMetadata(key, value) {
+    this.runWithRetry(() => {
+      this.db.prepare("INSERT OR REPLACE INTO metadata(key, value) VALUES(?, ?)").run(key, value);
     });
   }
   clearAll() {
     this.runWithRetry(() => {
-      this.db.exec("DELETE FROM symbols");
-      this.db.exec("DELETE FROM files");
-      this.db.exec("DELETE FROM refs");
-      if (this.ftsAvailable) this.db.exec("DELETE FROM symbols_fts");
+      this.db.exec("BEGIN IMMEDIATE");
+      try {
+        this.db.exec("DELETE FROM refs");
+        this.db.exec("DELETE FROM symbols");
+        this.db.exec("DELETE FROM files");
+        if (this.ftsAvailable) this.db.exec("DELETE FROM symbols_fts");
+        this.db.exec("COMMIT");
+      } catch (err) {
+        this.db.exec("ROLLBACK");
+        throw err;
+      }
     });
   }
   // ─── Ref CRUD ────────────────────────────────────────────────────────────────
@@ -831,6 +922,7 @@ var IndexStore = class {
         const allInserted = [];
         const refsToInsert = [];
         for (const entry of entries) {
+          const insertedForEntry = [];
           for (const s of entry.symbols) {
             const id = nextId++;
             symStmt.run(
@@ -848,9 +940,11 @@ var IndexStore = class {
               s.file
             );
             ftsStmt?.run(id, buildIndexableText(s.name, s.signature, s.docComment));
-            allInserted.push({ ...s, id });
+            const inserted = { ...s, id };
+            allInserted.push(inserted);
+            insertedForEntry.push(inserted);
           }
-          for (const r of entry.refs) refsToInsert.push(r);
+          refsToInsert.push(...assignRefsToSymbols(entry.refs, insertedForEntry));
         }
         if (refsToInsert.length > 0) {
           const refStmt = this.db.prepare(
@@ -888,9 +982,7 @@ var IndexStore = class {
    */
   deleteRefsForFile(file) {
     this.runWithRetry(() => {
-      this.db.prepare(
-        "DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file = ?)"
-      ).run(file);
+      this.db.prepare("DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file = ?)").run(file);
     });
   }
   /**
@@ -931,9 +1023,7 @@ var IndexStore = class {
    * Find all references FROM a given symbol (what does this symbol call/use?).
    */
   findRefsFrom(symbolId) {
-    return this.db.prepare(
-      "SELECT id, from_id, to_name, to_id, call_type, line FROM refs WHERE from_id = ?"
-    ).all(symbolId).map((r) => ({
+    return this.db.prepare("SELECT id, from_id, to_name, to_id, call_type, line FROM refs WHERE from_id = ?").all(symbolId).map((r) => ({
       id: r.id,
       fromId: r.from_id,
       toName: r.to_name,
@@ -950,6 +1040,325 @@ var IndexStore = class {
       return 0;
     }
   }
+  // ─── CodeMap graph aggregation ──────────────────────────────────────────────
+  /**
+   * Derive a monorepo package name from an absolute file path.
+   * Handles both `packages/<name>/...` (workspace) and `src/<name>/...` layouts.
+   * Returns `undefined` for files outside any recognisable package structure.
+   */
+  static derivePackage(filePath) {
+    const f = filePath.replace(/\\/g, "/");
+    const pkgsIdx = f.indexOf("/packages/");
+    if (pkgsIdx !== -1) {
+      const rest = f.slice(pkgsIdx + "/packages/".length);
+      const seg = rest.split("/")[0];
+      return seg ? `@wrongstack/${seg}` : void 0;
+    }
+    const appsIdx = f.indexOf("/apps/");
+    if (appsIdx !== -1) {
+      const rest = f.slice(appsIdx + "/apps/".length);
+      const seg = rest.split("/")[0];
+      return seg ? `app:${seg}` : void 0;
+    }
+    return void 0;
+  }
+  static packageFromImport(moduleName) {
+    if (!moduleName.startsWith("@wrongstack/")) return void 0;
+    const parts = moduleName.split("/");
+    return parts[1] ? `@wrongstack/${parts[1]}` : void 0;
+  }
+  static resolveRelativeImport(fromFile, moduleName, indexedFiles) {
+    if (!moduleName.startsWith(".")) return void 0;
+    const normalizedFrom = fromFile.replace(/\\/g, "/");
+    const absolute = path.posix.normalize(
+      path.posix.join(path.posix.dirname(normalizedFrom), moduleName)
+    );
+    const extension = path.posix.extname(absolute);
+    const base = extension ? absolute.slice(0, -extension.length) : absolute;
+    const candidates = [
+      absolute,
+      ...[".ts", ".tsx", ".js", ".jsx", ".mts", ".cts"].map((ext) => `${base}${ext}`),
+      ...[".ts", ".tsx", ".js", ".jsx"].map((ext) => path.posix.join(absolute, `index${ext}`)),
+      ...[".ts", ".tsx", ".js", ".jsx"].map((ext) => path.posix.join(base, `index${ext}`))
+    ];
+    const indexedByPortablePath = new Map(
+      [...indexedFiles].map((file) => [file.replace(/\\/g, "/").toLocaleLowerCase(), file])
+    );
+    for (const candidate of candidates) {
+      const indexed = indexedByPortablePath.get(candidate.toLocaleLowerCase());
+      if (indexed) return indexed;
+    }
+    return void 0;
+  }
+  /**
+   * Package-level graph: each workspace package is a node; edges are derived
+   * from cross-package symbol references (a symbol in package A references a
+   * symbol resolved in package B). Node metadata includes symbol/file counts.
+   */
+  getPackageGraph() {
+    const symbols = this.db.prepare("SELECT file, id, name, kind, lang, line FROM symbols ORDER BY id").all();
+    const pkgNodes = /* @__PURE__ */ new Map();
+    const fileToPkg = /* @__PURE__ */ new Map();
+    const symbolToPkg = /* @__PURE__ */ new Map();
+    for (const s of symbols) {
+      const pkg = _IndexStore.derivePackage(s.file) ?? "(root)";
+      fileToPkg.set(s.file, pkg);
+      symbolToPkg.set(s.id, pkg);
+      const node = pkgNodes.get(pkg);
+      if (node) {
+        node.symbolCount = (node.symbolCount ?? 0) + 1;
+      } else {
+        pkgNodes.set(pkg, {
+          id: `pkg:${pkg}`,
+          label: pkg,
+          kind: "package",
+          package: pkg,
+          symbolCount: 1,
+          fileCount: 0
+        });
+      }
+    }
+    const files = this.db.prepare("SELECT DISTINCT file FROM files").all();
+    for (const { file } of files) {
+      const pkg = _IndexStore.derivePackage(file) ?? "(root)";
+      const node = pkgNodes.get(pkg);
+      if (node) node.fileCount = (node.fileCount ?? 0) + 1;
+    }
+    const refRows = this.db.prepare(
+      `SELECT r.from_id, r.to_id, r.call_type
+       FROM refs r
+       WHERE r.to_id IS NOT NULL`
+    ).all();
+    const edgeMap = /* @__PURE__ */ new Map();
+    for (const r of refRows) {
+      if (r.call_type === "import") continue;
+      const fromPkg = symbolToPkg.get(r.from_id);
+      const toPkg = symbolToPkg.get(r.to_id);
+      if (!fromPkg || !toPkg || fromPkg === toPkg) continue;
+      const key = `${fromPkg}\0${toPkg}`;
+      let e = edgeMap.get(key);
+      if (!e) {
+        e = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, e);
+      }
+      e.weight++;
+      e.types.set(r.call_type, (e.types.get(r.call_type) ?? 0) + 1);
+    }
+    const importRows = this.db.prepare(
+      `SELECT r.from_id, r.to_name
+       FROM refs r
+       WHERE r.call_type = 'import'`
+    ).all();
+    for (const r of importRows) {
+      const fromPkg = symbolToPkg.get(r.from_id);
+      const toPkg = _IndexStore.packageFromImport(r.to_name);
+      if (!fromPkg || !toPkg || fromPkg === toPkg || !pkgNodes.has(toPkg)) continue;
+      const key = `${fromPkg}\0${toPkg}`;
+      let edge = edgeMap.get(key);
+      if (!edge) {
+        edge = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, edge);
+      }
+      edge.weight++;
+      edge.types.set("import", (edge.types.get("import") ?? 0) + 1);
+    }
+    const edges = [];
+    for (const [key, e] of edgeMap) {
+      const [source, target] = key.split("\0");
+      let bestType = "call";
+      let bestCount = 0;
+      for (const [t, c] of e.types) {
+        if (c > bestCount) {
+          bestType = t;
+          bestCount = c;
+        }
+      }
+      edges.push({
+        source: `pkg:${source}`,
+        target: `pkg:${target}`,
+        weight: e.weight,
+        refType: bestType
+      });
+    }
+    return { nodes: [...pkgNodes.values()], edges };
+  }
+  /**
+   * File-level graph for a single package: each file is a node; edges are
+   * derived from cross-file symbol references within the package.
+   */
+  getFileGraph(packageFilter) {
+    const allSymbols = this.db.prepare("SELECT file, id, name, kind, lang, line FROM symbols ORDER BY id").all();
+    const pkgSyms = allSymbols.filter(
+      (s) => (_IndexStore.derivePackage(s.file) ?? "(root)") === packageFilter
+    );
+    if (pkgSyms.length === 0) return { nodes: [], edges: [] };
+    const fileNodes = /* @__PURE__ */ new Map();
+    const symToFile = /* @__PURE__ */ new Map();
+    const fileStats = /* @__PURE__ */ new Map();
+    for (const s of allSymbols) {
+      symToFile.set(s.id, s.file);
+      const current = fileStats.get(s.file);
+      fileStats.set(s.file, {
+        count: (current?.count ?? 0) + 1,
+        lang: current?.lang ?? s.lang
+      });
+    }
+    const localFiles = new Set(pkgSyms.map((s) => s.file));
+    const indexedFiles = new Set(allSymbols.map((s) => s.file));
+    const ensureFileNode = (file) => {
+      if (fileNodes.has(file)) return;
+      const stats = fileStats.get(file);
+      fileNodes.set(file, {
+        id: `file:${file}`,
+        label: file.replace(/\\/g, "/").split("/").pop() ?? file,
+        kind: "file",
+        package: _IndexStore.derivePackage(file) ?? "(root)",
+        file,
+        symbolCount: stats?.count ?? 0,
+        lang: stats?.lang,
+        external: !localFiles.has(file)
+      });
+    };
+    for (const file of localFiles) {
+      ensureFileNode(file);
+    }
+    const refRows = this.db.prepare(
+      `SELECT r.from_id, r.to_id, r.call_type
+       FROM refs r
+       WHERE r.to_id IS NOT NULL`
+    ).all();
+    const edgeMap = /* @__PURE__ */ new Map();
+    for (const r of refRows) {
+      if (r.call_type === "import") continue;
+      const fromFile = symToFile.get(r.from_id);
+      const toFile = symToFile.get(r.to_id);
+      if (!fromFile || !toFile || fromFile === toFile) continue;
+      if (!localFiles.has(fromFile) && !localFiles.has(toFile)) continue;
+      ensureFileNode(fromFile);
+      ensureFileNode(toFile);
+      const key = `${fromFile}\0${toFile}`;
+      let e = edgeMap.get(key);
+      if (!e) {
+        e = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, e);
+      }
+      e.weight++;
+      e.types.set(r.call_type, (e.types.get(r.call_type) ?? 0) + 1);
+    }
+    const importRows = this.db.prepare(
+      `SELECT r.from_id, r.to_name
+       FROM refs r
+       WHERE r.call_type = 'import'`
+    ).all();
+    for (const r of importRows) {
+      const fromFile = symToFile.get(r.from_id);
+      if (!fromFile || !localFiles.has(fromFile)) continue;
+      const toFile = _IndexStore.resolveRelativeImport(fromFile, r.to_name, indexedFiles);
+      if (!toFile || fromFile === toFile) continue;
+      ensureFileNode(fromFile);
+      ensureFileNode(toFile);
+      const key = `${fromFile}\0${toFile}`;
+      let edge = edgeMap.get(key);
+      if (!edge) {
+        edge = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, edge);
+      }
+      edge.weight++;
+      edge.types.set("import", (edge.types.get("import") ?? 0) + 1);
+    }
+    const edges = [];
+    for (const [key, e] of edgeMap) {
+      const [source, target] = key.split("\0");
+      let bestType = "call";
+      let bestCount = 0;
+      for (const [t, c] of e.types) {
+        if (c > bestCount) {
+          bestType = t;
+          bestCount = c;
+        }
+      }
+      edges.push({
+        source: `file:${source}`,
+        target: `file:${target}`,
+        weight: e.weight,
+        refType: bestType
+      });
+    }
+    return { nodes: [...fileNodes.values()], edges };
+  }
+  /**
+   * Symbol-level graph for a single file: each symbol is a node; edges are
+   * derived from intra-file and cross-file symbol references (who calls whom).
+   */
+  getSymbolGraph(fileFilter) {
+    const allSymbols = this.db.prepare(
+      "SELECT id, name, kind, lang, file, line, signature, scope FROM symbols ORDER BY file, line, id"
+    ).all();
+    const syms = allSymbols.filter((symbol) => symbol.file === fileFilter);
+    if (syms.length === 0) return { nodes: [], edges: [] };
+    const symById = new Map(allSymbols.map((symbol) => [symbol.id, symbol]));
+    const relatedIds = new Set(syms.map((symbol) => symbol.id));
+    const toGraphNode = (s) => ({
+      id: `sym:${s.id}`,
+      label: s.name,
+      kind: "symbol",
+      symbolId: s.id,
+      symbolKind: s.kind,
+      file: s.file,
+      package: _IndexStore.derivePackage(s.file) ?? "(root)",
+      lang: s.lang,
+      line: s.line,
+      signature: s.signature,
+      scope: s.scope,
+      external: s.file !== fileFilter
+    });
+    const symIds = new Set(syms.map((s) => s.id));
+    const refRows = this.db.prepare(
+      `SELECT r.from_id, r.to_id, r.to_name, r.call_type, r.line
+       FROM refs r
+       WHERE r.from_id IN (SELECT id FROM symbols WHERE file = ?)
+          OR r.to_id IN (SELECT id FROM symbols WHERE file = ?)`
+    ).all(fileFilter, fileFilter);
+    const edgeMap = /* @__PURE__ */ new Map();
+    for (const r of refRows) {
+      if (r.to_id === null) continue;
+      if (!symIds.has(r.from_id) && !symIds.has(r.to_id)) continue;
+      relatedIds.add(r.from_id);
+      relatedIds.add(r.to_id);
+      const key = `${r.from_id}\0${r.to_id}`;
+      let e = edgeMap.get(key);
+      if (!e) {
+        e = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, e);
+      }
+      e.weight++;
+      e.types.set(r.call_type, (e.types.get(r.call_type) ?? 0) + 1);
+    }
+    const edges = [];
+    for (const [key, e] of edgeMap) {
+      const [fromId, toId] = key.split("\0").map(Number);
+      let bestType = "call";
+      let bestCount = 0;
+      for (const [t, c] of e.types) {
+        if (c > bestCount) {
+          bestType = t;
+          bestCount = c;
+        }
+      }
+      edges.push({
+        source: `sym:${fromId}`,
+        target: `sym:${toId}`,
+        weight: e.weight,
+        refType: bestType
+      });
+    }
+    const nodes = [...relatedIds].map((id) => symById.get(id)).filter((symbol) => symbol !== void 0).sort((a, b) => {
+      const aExternal = a.file === fileFilter ? 0 : 1;
+      const bExternal = b.file === fileFilter ? 0 : 1;
+      return aExternal - bExternal || a.file.localeCompare(b.file) || a.line - b.line || a.id - b.id;
+    }).map(toGraphNode);
+    return { nodes, edges };
+  }
   close() {
     this.stmtCache.clear();
     try {
@@ -960,14 +1369,14 @@ var IndexStore = class {
 };
 
 // src/codebase-index/background-indexer.ts
-import * as fs7 from "node:fs";
+import * as fs8 from "node:fs";
 import { fileURLToPath } from "node:url";
 import { Worker } from "node:worker_threads";
 
 // src/codebase-index/indexer.ts
 import { expectDefined as expectDefined5 } from "@wrongstack/core";
-import * as fs6 from "node:fs/promises";
-import * as path7 from "node:path";
+import * as fs7 from "node:fs/promises";
+import * as path8 from "node:path";
 import { compileGlob as compileGlob2 } from "@wrongstack/core";
 
 // src/codebase-index/ts-parser.ts
@@ -1044,6 +1453,14 @@ function getJsDoc(node, sourceFile) {
   }
   return "";
 }
+function hasFunctionLikeAncestor(node) {
+  let current = node.parent;
+  while (current) {
+    if (ts.isFunctionLike(current)) return true;
+    current = current.parent;
+  }
+  return false;
+}
 function buildScope(node) {
   const parts = [];
   let current = node.parent;
@@ -1071,6 +1488,10 @@ function parseSymbols(opts) {
   function visit(node) {
     const kind = kindOf(node);
     if (kind) {
+      if ((kind === "const" || kind === "let" || kind === "var" || kind === "parameter") && hasFunctionLikeAncestor(node)) {
+        ts.forEachChild(node, visit);
+        return;
+      }
       const nameNode = node.name;
       if (!nameNode || !ts.isIdentifier(nameNode)) return;
       const name = nameNode.text;
@@ -1160,8 +1581,34 @@ function detectLang(file) {
 // src/codebase-index/go-parser.ts
 import { spawn } from "node:child_process";
 import * as os from "node:os";
+import * as path3 from "node:path";
+import * as fs3 from "node:fs/promises";
+
+// src/_win32-resolve.ts
+import * as fs2 from "node:fs";
 import * as path2 from "node:path";
-import * as fs2 from "node:fs/promises";
+function resolveWin32Command(cmd) {
+  if (process.platform !== "win32") return cmd;
+  if (cmd.includes("/") || cmd.includes("\\") || path2.extname(cmd.replace(/\//g, "\\"))) {
+    return cmd;
+  }
+  const pathext = (process.env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS;.MSC").toLowerCase().split(";");
+  const pathDirs = (process.env["PATH"] ?? "").split(path2.delimiter);
+  for (const dir of pathDirs) {
+    const base = path2.join(dir, cmd);
+    for (const ext of pathext) {
+      const full = `${base}${ext}`;
+      try {
+        fs2.accessSync(full, fs2.constants.X_OK);
+        return full;
+      } catch {
+      }
+    }
+  }
+  return cmd;
+}
+
+// src/codebase-index/go-parser.ts
 async function parseSymbols2(opts) {
   const { file, content, lang } = opts;
   try {
@@ -1462,31 +1909,46 @@ func formatType(t ast.Expr) string {
 }
 `;
 async function syncGoParse(filePath, content, lang) {
-  const tmpDir = await fs2.mkdtemp(path2.join(os.tmpdir(), "ws-go-parse-"));
+  const tmpDir = await fs3.mkdtemp(path3.join(os.tmpdir(), "ws-go-parse-"));
   try {
-    const scriptPath = path2.join(tmpDir, "parse.go");
-    await fs2.writeFile(scriptPath, GO_PARSE_SCRIPT, "utf8");
-    const proc = spawn("go", ["run", scriptPath], {
-      stdio: ["pipe", "pipe", "pipe"],
-      windowsHide: true
-    });
-    let stdout = "";
-    proc.stdout?.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    proc.stdin?.write(content);
-    proc.stdin?.end();
-    const { code } = await Promise.race([
-      new Promise((resolve2) => {
-        proc.on("close", (c) => resolve2({ code: c }));
-      }),
-      new Promise(
-        (_, reject) => setTimeout(() => {
+    const scriptPath = path3.join(tmpDir, "parse.go");
+    await fs3.writeFile(scriptPath, GO_PARSE_SCRIPT, "utf8");
+    const goBinary = resolveWin32Command("go");
+    const goResult = await new Promise(
+      (resolve2, reject) => {
+        let settled = false;
+        const proc = spawn(goBinary, ["run", scriptPath], {
+          stdio: ["pipe", "pipe", "pipe"],
+          windowsHide: true
+        });
+        proc.on("error", (err) => {
+          if (settled) return;
+          settled = true;
+          reject(err);
+        });
+        let stdout2 = "";
+        proc.stdout?.on("data", (chunk) => {
+          stdout2 += chunk.toString();
+        });
+        proc.stderr?.resume();
+        proc.stdin?.write(content);
+        proc.stdin?.end();
+        const timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
           proc.kill("SIGKILL");
           reject(new Error("timeout"));
-        }, 15e3)
-      )
-    ]).catch(() => ({ code: -1 }));
+        }, 15e3);
+        timer.unref?.();
+        proc.on("close", (code2) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve2({ code: code2, stdout: stdout2 });
+        });
+      }
+    );
+    const { code, stdout } = goResult;
     if (code !== 0 || !stdout.trim()) {
       return { file: filePath, lang, symbols: [], mtimeMs: Date.now() };
     }
@@ -1508,15 +1970,15 @@ async function syncGoParse(filePath, content, lang) {
   } catch {
     return { file: filePath, lang, symbols: [], mtimeMs: Date.now() };
   } finally {
-    await fs2.rm(tmpDir, { recursive: true, force: true });
+    await fs3.rm(tmpDir, { recursive: true, force: true });
   }
 }
 
 // src/codebase-index/py-parser.ts
-import { spawn as spawn2 } from "node:child_process";
-import * as fs3 from "node:fs/promises";
+import { spawn as spawn2, spawnSync } from "node:child_process";
+import * as fs4 from "node:fs/promises";
 import * as os2 from "node:os";
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 async function parseSymbols3(opts) {
   const { file, content, lang } = opts;
   try {
@@ -1728,36 +2190,74 @@ visitor.visit(tree)
 
 print(json.dumps([s.to_dict() for s in syms]))
 `;
-var _cachedScriptPath = null;
-async function syncPyParse(filePath, content, lang) {
-  try {
-    if (!_cachedScriptPath) {
-      const tmpDir = path3.join(os2.tmpdir(), "ws-py-parse");
-      await fs3.mkdir(tmpDir, { recursive: true });
-      _cachedScriptPath = path3.join(tmpDir, "parse.py");
-      await fs3.writeFile(_cachedScriptPath, PY_PARSE_SCRIPT, "utf8");
-    }
-    const proc = spawn2("python", [_cachedScriptPath, filePath], {
+function resolvePython() {
+  const candidates = process.platform === "win32" ? ["python3", "python", "py"] : ["python3", "python"];
+  for (const name of candidates) {
+    const resolved = resolveWin32Command(name);
+    const result = spawnSync(resolved, ["--version"], {
+      stdio: "pipe",
+      timeout: 5e3
+    });
+    if (result.error) continue;
+    if (result.status !== 0) continue;
+    return resolved;
+  }
+  return null;
+}
+function spawnPyParser(pyBinary, scriptPath, filePath, content) {
+  return new Promise((resolve2, reject) => {
+    let settled = false;
+    const proc = spawn2(pyBinary, [scriptPath, filePath], {
       stdio: ["pipe", "pipe", "pipe"],
       windowsHide: true
     });
+    proc.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    });
     proc.stdin?.write(content);
     proc.stdin?.end();
     let stdout = "";
     proc.stdout?.on("data", (chunk) => {
       stdout += chunk.toString();
     });
-    const { code } = await Promise.race([
-      new Promise((resolve2) => {
-        proc.on("close", (c) => resolve2({ code: c }));
-      }),
-      new Promise(
-        (_, reject) => setTimeout(() => {
-          proc.kill("SIGKILL");
-          reject(new Error("timeout"));
-        }, 15e3)
-      )
-    ]).catch(() => ({ code: -1 }));
+    proc.stderr?.resume();
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      proc.kill("SIGKILL");
+      reject(new Error("timeout"));
+    }, 15e3);
+    timer.unref?.();
+    proc.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve2({ code, stdout });
+    });
+  });
+}
+var _cachedScriptPath = null;
+var _cachedPyBinary = null;
+async function syncPyParse(filePath, content, lang) {
+  try {
+    if (!_cachedScriptPath) {
+      const tmpDir = path4.join(os2.tmpdir(), "ws-py-parse");
+      await fs4.mkdir(tmpDir, { recursive: true });
+      _cachedScriptPath = path4.join(tmpDir, "parse.py");
+      await fs4.writeFile(_cachedScriptPath, PY_PARSE_SCRIPT, "utf8");
+    }
+    if (!_cachedPyBinary) {
+      _cachedPyBinary = resolvePython();
+      if (!_cachedPyBinary) return { file: filePath, lang, symbols: [], mtimeMs: Date.now() };
+    }
+    const { code, stdout } = await spawnPyParser(
+      _cachedPyBinary,
+      _cachedScriptPath,
+      filePath,
+      content
+    );
     if (code !== 0 || !stdout.trim()) {
       return { file: filePath, lang, symbols: [], mtimeMs: Date.now() };
     }
@@ -1784,8 +2284,8 @@ async function syncPyParse(filePath, content, lang) {
 // src/codebase-index/rs-parser.ts
 import { expectDefined as expectDefined2 } from "@wrongstack/core";
 import { execFileSync, spawn as spawn3 } from "node:child_process";
-import * as fs4 from "node:fs/promises";
-import * as path4 from "node:path";
+import * as fs5 from "node:fs/promises";
+import * as path5 from "node:path";
 async function parseSymbols4(opts) {
   const { file, content, lang } = opts;
   const nativeAvailable = checkNativeParser();
@@ -1798,7 +2298,7 @@ async function parseSymbols4(opts) {
 function checkNativeParser() {
   try {
     execFileSync("rustc", ["--version"], { stdio: "pipe", windowsHide: true });
-    const toolsDir = path4.join(process.cwd(), "tools");
+    const toolsDir = path5.join(process.cwd(), "tools");
     try {
       execFileSync(
         "cargo",
@@ -1808,7 +2308,7 @@ function checkNativeParser() {
           "--format-version",
           "1",
           "--manifest-path",
-          path4.join(toolsDir, "Cargo.toml")
+          path5.join(toolsDir, "Cargo.toml")
         ],
         { stdio: "pipe", windowsHide: true }
       );
@@ -1822,34 +2322,49 @@ function checkNativeParser() {
 }
 async function tryNativeParse(file, content) {
   try {
-    const toolsDir = path4.join(process.cwd(), "tools");
-    const crateDir = path4.join(toolsDir, "syn-parser");
-    const tmpFile = path4.join(crateDir, "src", "input.rs");
-    await fs4.writeFile(tmpFile, content, "utf8");
-    const proc = spawn3(
-      "cargo",
-      ["run", "--manifest-path", path4.join(toolsDir, "Cargo.toml")],
-      {
-        cwd: process.cwd(),
-        stdio: ["pipe", "pipe", "pipe"],
-        windowsHide: true
-      }
-    );
-    let stdout = "";
-    proc.stdout?.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    const { code } = await Promise.race([
-      new Promise((resolve2) => {
-        proc.on("close", (c) => resolve2({ code: c }));
-      }),
-      new Promise(
-        (_, reject) => setTimeout(() => {
+    const toolsDir = path5.join(process.cwd(), "tools");
+    const crateDir = path5.join(toolsDir, "syn-parser");
+    const tmpFile = path5.join(crateDir, "src", "input.rs");
+    await fs5.writeFile(tmpFile, content, "utf8");
+    const cargoBinary = resolveWin32Command("cargo");
+    const result = await new Promise(
+      (resolve2, reject) => {
+        let settled = false;
+        const proc = spawn3(
+          cargoBinary,
+          ["run", "--manifest-path", path5.join(toolsDir, "Cargo.toml")],
+          {
+            cwd: process.cwd(),
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true
+          }
+        );
+        proc.on("error", (err) => {
+          if (settled) return;
+          settled = true;
+          reject(err);
+        });
+        let stdout2 = "";
+        proc.stdout?.on("data", (chunk) => {
+          stdout2 += chunk.toString();
+        });
+        proc.stderr?.resume();
+        const timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
           proc.kill("SIGKILL");
           reject(new Error("timeout"));
-        }, 15e3)
-      )
-    ]).catch(() => ({ code: -1 }));
+        }, 15e3);
+        timer.unref?.();
+        proc.on("close", (c) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve2({ code: c, stdout: stdout2 });
+        });
+      }
+    );
+    const { code, stdout } = result;
     if (code === 0 && stdout.trim()) {
       const symbols = JSON.parse(stdout.trim());
       return {
@@ -1932,7 +2447,7 @@ function regexParse(opts) {
 
 // src/codebase-index/json-parser.ts
 import { expectDefined as expectDefined3 } from "@wrongstack/core";
-import * as path5 from "node:path";
+import * as path6 from "node:path";
 function parseSymbols5(opts) {
   const { file, content, lang } = opts;
   try {
@@ -1944,9 +2459,9 @@ function parseSymbols5(opts) {
 function regexParse2(opts) {
   const { file, content, lang } = opts;
   const symbols = [];
-  const basename2 = path5.basename(file).toLowerCase();
-  const isPackageJson = basename2 === "package.json";
-  const isTsconfig = basename2 === "tsconfig.json" || basename2 === "tsconfig.build.json";
+  const basename3 = path6.basename(file).toLowerCase();
+  const isPackageJson = basename3 === "package.json";
+  const isTsconfig = basename3 === "tsconfig.json" || basename3 === "tsconfig.build.json";
   const isJsonSchema = content.includes("$schema") || content.includes("$id") || content.includes("$ref");
   const isOpenApi = content.includes("openapi") || content.includes("swagger");
   const lines = content.split("\n");
@@ -1970,11 +2485,11 @@ function regexParse2(opts) {
     const line = lineFromOffset(offset);
     symbols.push(
       makeSymbol({
-        name: path5.basename(file),
+        name: path6.basename(file),
         kind: "object",
         line,
         col: 0,
-        signature: `"${path5.basename(file)}" = { ... }`,
+        signature: `"${path6.basename(file)}" = { ... }`,
         file,
         lang
       })
@@ -2285,8 +2800,8 @@ function makeSymbol2(opts) {
 }
 
 // src/codebase-index/gitignore.ts
-import * as fs5 from "node:fs/promises";
-import * as path6 from "node:path";
+import * as fs6 from "node:fs/promises";
+import * as path7 from "node:path";
 import { compileGlob } from "@wrongstack/core";
 function globBody(glob) {
   return compileGlob(glob).source.replace(/^\^/, "").replace(/\$$/, "");
@@ -2332,7 +2847,7 @@ function compileGitignore(lines) {
 async function loadGitignoreMatcher(projectRoot) {
   let lines = [];
   try {
-    const raw = await fs5.readFile(path6.join(projectRoot, ".gitignore"), "utf8");
+    const raw = await fs6.readFile(path7.join(projectRoot, ".gitignore"), "utf8");
     lines = raw.split("\n");
   } catch {
   }
@@ -2348,9 +2863,7 @@ function yieldEventLoop() {
 function throwIfAborted(signal) {
   if (!signal?.aborted) return;
   if (signal.reason instanceof Error) throw signal.reason;
-  throw new Error(
-    typeof signal.reason === "string" ? signal.reason : "Indexing cancelled"
-  );
+  throw new Error(typeof signal.reason === "string" ? signal.reason : "Indexing cancelled");
 }
 function isAbortError(err) {
   return err instanceof DOMException && err.name === "AbortError";
@@ -2366,8 +2879,20 @@ var DEFAULT_IGNORE = [
   "__snapshots__",
   ".nyc_output"
 ];
+var DEFAULT_IGNORE_FILES = /* @__PURE__ */ new Set(["package-lock.json", "pnpm-lock.yaml", "pnpm-lock.yml"]);
+var MAX_INDEX_FILE_BYTES = 5 * 1024 * 1024;
+function isWithinProject(projectRoot, file) {
+  const rel = path8.relative(projectRoot, file);
+  return rel !== "" && !rel.startsWith(`..${path8.sep}`) && rel !== ".." && !path8.isAbsolute(rel);
+}
+function isMissingPathError(err) {
+  const code = err?.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
 async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
   const results = [];
+  const errors = [];
+  let complete = true;
   const ignoreSet = /* @__PURE__ */ new Set([...DEFAULT_IGNORE, ...ignore]);
   const globs = [
     { ext: ".ts", pat: compileGlob2("**/*.ts") },
@@ -2390,21 +2915,23 @@ async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
     }
     let entries;
     try {
-      entries = await fs6.readdir(dir, { withFileTypes: true });
-    } catch {
+      entries = await fs7.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      complete = false;
+      errors.push(`scan error: ${dir}: ${err instanceof Error ? err.message : String(err)}`);
       return;
     }
     dirCount++;
     for (const e of entries) {
       if (ignoreSet.has(e.name)) continue;
-      const full = path7.join(dir, e.name);
-      const rel = path7.relative(projectRoot, full).replace(/\\/g, "/");
+      const full = path8.join(dir, e.name);
+      const rel = path8.relative(projectRoot, full).replace(/\\/g, "/");
       if (e.isDirectory()) {
         if (isGitIgnored(rel, true)) continue;
         await walk(full);
       } else if (e.isFile()) {
-        if (isGitIgnored(rel, false)) continue;
-        const ext = path7.extname(e.name);
+        if (DEFAULT_IGNORE_FILES.has(e.name) || isGitIgnored(rel, false)) continue;
+        const ext = path8.extname(e.name).toLowerCase();
         for (const { ext: extName, pat } of globs) {
           if (ext === extName && (pat.test(rel) || pat.test(e.name))) {
             results.push(full);
@@ -2415,7 +2942,7 @@ async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
     }
   };
   await walk(projectRoot);
-  return results;
+  return { files: results, complete, errors };
 }
 async function parseFile(file, content, lang) {
   switch (lang) {
@@ -2438,6 +2965,26 @@ async function parseFile(file, content, lang) {
       return { file, lang, symbols: [], mtimeMs: Date.now() };
   }
 }
+function assignRefsToSymbols2(refs, symbols) {
+  if (refs.length === 0 || symbols.length === 0) return [];
+  const ordered = [...symbols].sort((a, b) => a.line - b.line || a.col - b.col || a.id - b.id);
+  const seen = /* @__PURE__ */ new Set();
+  const assigned = [];
+  for (const ref of refs) {
+    let owner;
+    for (const symbol of ordered) {
+      if (symbol.line > ref.line) break;
+      owner = symbol;
+    }
+    if (!owner && ref.callType === "import") owner = ordered[0];
+    if (!owner || owner.id <= 0) continue;
+    const key = `${owner.id}:${ref.toName}:${ref.callType}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    assigned.push({ ...ref, fromId: owner.id });
+  }
+  return assigned;
+}
 async function runIndexer(_ctx, opts) {
   const store = new IndexStore(opts.projectRoot, { indexDir: opts.indexDir });
   try {
@@ -2450,7 +2997,9 @@ async function runIndexer(_ctx, opts) {
   }
 }
 async function runIndexerWithStore(store, opts) {
-  const { projectRoot, force = false, langs, ignore = [], signal } = opts;
+  const { projectRoot, langs, ignore = [], signal } = opts;
+  const relationGraphVersion = "2";
+  const force = (opts.force ?? false) || store.getMetadata("relation_graph_version") !== relationGraphVersion;
   const startMs = Date.now();
   const errors = [];
   const langStats = {};
@@ -2459,10 +3008,18 @@ async function runIndexerWithStore(store, opts) {
   const isGitIgnored = await loadGitignoreMatcher(projectRoot);
   let files;
   let discoveredFiles = null;
+  let discoveryComplete = true;
   if (opts.files && opts.files.length > 0) {
-    files = opts.files.map((f) => path7.resolve(projectRoot, f)).filter((f) => !isGitIgnored(path7.relative(projectRoot, f).replace(/\\/g, "/"), false));
+    files = opts.files.map((f) => path8.resolve(projectRoot, f)).filter((f) => {
+      if (!isWithinProject(projectRoot, f)) return false;
+      const rel = path8.relative(projectRoot, f).replace(/\\/g, "/");
+      return !rel.split("/").some((seg) => DEFAULT_IGNORE.includes(seg)) && !DEFAULT_IGNORE_FILES.has(path8.basename(f)) && !isGitIgnored(rel, false);
+    });
   } else {
-    files = await findSourceFiles(projectRoot, ignore, isGitIgnored, signal);
+    const discovery = await findSourceFiles(projectRoot, ignore, isGitIgnored, signal);
+    files = discovery.files;
+    errors.push(...discovery.errors);
+    discoveryComplete = discovery.complete;
     discoveredFiles = new Set(files);
   }
   if (langs && langs.length > 0) {
@@ -2487,36 +3044,66 @@ async function runIndexerWithStore(store, opts) {
     }
     const statOpts = signal ? { signal } : {};
     const statReadParse = await Promise.allSettled(
-      batchFiles.map(async (file) => {
-        let stat2;
-        try {
-          stat2 = await fs6.stat(file, statOpts);
-        } catch (e) {
-          if (isAbortError(e)) throw e;
-          return { file, stat: null, lang: "", parsed: null, error: `stat error: ${e instanceof Error ? e.message : String(e)}` };
-        }
-        if (!stat2.isFile()) return { file, stat: stat2, lang: "", parsed: null };
-        const lang = detectLang(file);
-        if (!lang) return { file, stat: stat2, lang: "", parsed: null };
-        const meta = existingMeta.get(file);
-        if (!force && meta && meta.mtimeMs === Math.floor(stat2.mtimeMs)) {
-          return { file, stat: stat2, lang, parsed: null, skippedMeta: meta };
-        }
-        let content;
-        try {
-          content = await fs6.readFile(file, { encoding: "utf8", signal });
-        } catch (e) {
-          if (isAbortError(e)) throw e;
-          return { file, stat: stat2, lang, parsed: null, error: `read error: ${e instanceof Error ? e.message : String(e)}` };
-        }
-        let parsed;
-        try {
-          parsed = await parseFile(file, content, lang);
-        } catch (e) {
-          return { file, stat: stat2, lang, parsed: null, error: `parse error: ${e instanceof Error ? e.message : String(e)}` };
+      batchFiles.map(
+        async (file) => {
+          let stat2;
+          try {
+            stat2 = await fs7.stat(file, statOpts);
+          } catch (e) {
+            if (isAbortError(e)) throw e;
+            return {
+              file,
+              stat: null,
+              lang: "",
+              parsed: null,
+              error: `stat error: ${e instanceof Error ? e.message : String(e)}`,
+              missing: isMissingPathError(e)
+            };
+          }
+          if (!stat2.isFile()) return { file, stat: stat2, lang: "", parsed: null };
+          const lang = detectLang(file);
+          if (!lang) return { file, stat: stat2, lang: "", parsed: null };
+          if (stat2.size > MAX_INDEX_FILE_BYTES) {
+            return {
+              file,
+              stat: stat2,
+              lang,
+              parsed: null,
+              error: `file too large (${stat2.size} bytes; max ${MAX_INDEX_FILE_BYTES})`
+            };
+          }
+          const meta = existingMeta.get(file);
+          if (!force && meta && meta.mtimeMs === Math.floor(stat2.mtimeMs)) {
+            return { file, stat: stat2, lang, parsed: null, skippedMeta: meta };
+          }
+          let content;
+          try {
+            content = await fs7.readFile(file, { encoding: "utf8", signal });
+          } catch (e) {
+            if (isAbortError(e)) throw e;
+            return {
+              file,
+              stat: stat2,
+              lang,
+              parsed: null,
+              error: `read error: ${e instanceof Error ? e.message : String(e)}`
+            };
+          }
+          let parsed;
+          try {
+            parsed = await parseFile(file, content, lang);
+          } catch (e) {
+            return {
+              file,
+              stat: stat2,
+              lang,
+              parsed: null,
+              error: `parse error: ${e instanceof Error ? e.message : String(e)}`
+            };
+          }
+          return { file, stat: stat2, lang, parsed, content };
         }
-        return { file, stat: stat2, lang, parsed, content };
-      })
+      )
     );
     const batchEntries = [];
     const deleteForFiles = [];
@@ -2531,8 +3118,8 @@ async function runIndexerWithStore(store, opts) {
       }
       const result = settled.value;
       if (result.error) {
-        if (result.stat) store.deleteFile(file);
-        if (result.error.includes("error:")) errors.push(result.error);
+        if (result.missing) store.deleteFile(file);
+        errors.push(`${file}: ${result.error}`);
         continue;
       }
       const { stat: stat2, lang, parsed } = result;
@@ -2556,6 +3143,8 @@ async function runIndexerWithStore(store, opts) {
         continue;
       }
       if (parsed.symbols.length === 0) {
+        store.deleteRefsForFile(file);
+        store.deleteSymbolsForFile(file);
         store.upsertFile({
           file,
           lang,
@@ -2566,15 +3155,11 @@ async function runIndexerWithStore(store, opts) {
         filesIndexed++;
         continue;
       }
-      const refs = [];
-      if (parsed.refs && parsed.refs.length > 0) {
-        for (const r of parsed.refs) refs.push({ ...r, fromId: 0 });
-      }
       batchEntries.push({
         file,
         lang,
         symbols: parsed.symbols,
-        refs,
+        refs: parsed.refs ?? [],
         mtimeMs: Math.floor(stat2.mtimeMs),
         symbolCount: parsed.symbols.length
       });
@@ -2582,34 +3167,12 @@ async function runIndexerWithStore(store, opts) {
     }
     if (batchEntries.length > 0) {
       try {
-        const inserted = store.commitBatch(batchEntries, { deleteForFiles });
-        let cursor = 0;
+        store.commitBatch(batchEntries, { deleteForFiles });
         for (const entry of batchEntries) {
           const count = entry.symbols.length;
-          const symbolsWithIds = inserted.slice(cursor, cursor + count);
-          cursor += count;
           symbolsIndexed += count;
           langStats[entry.lang] = (langStats[entry.lang] ?? 0) + count;
           filesIndexed++;
-          if (entry.refs.length > 0 && symbolsWithIds.length > 0) {
-            const refsByLine = /* @__PURE__ */ new Map();
-            for (let i = 0; i < symbolsWithIds.length; i++) {
-              const sym = symbolsWithIds[i];
-              let arr = refsByLine.get(sym.line);
-              if (!arr) {
-                arr = [];
-                refsByLine.set(sym.line, arr);
-              }
-              arr.push(i);
-            }
-            for (const ref of entry.refs) {
-              const indices = refsByLine.get(ref.line);
-              if (indices && indices.length > 0) {
-                const idx = indices.shift();
-                ref.fromId = symbolsWithIds[idx].id;
-              }
-            }
-          }
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -2623,23 +3186,7 @@ async function runIndexerWithStore(store, opts) {
             langStats[entry.lang] = (langStats[entry.lang] ?? 0) + symbolsWithIds.length;
             filesIndexed++;
             if (entry.refs.length > 0 && symbolsWithIds.length > 0) {
-              const refsByLine = /* @__PURE__ */ new Map();
-              for (const sym of symbolsWithIds) {
-                let arr = refsByLine.get(sym.line);
-                if (!arr) {
-                  arr = [];
-                  refsByLine.set(sym.line, arr);
-                }
-                arr.push(sym);
-              }
-              const fallbackBatch = [];
-              for (const ref of entry.refs) {
-                const syms = refsByLine.get(ref.line);
-                if (syms && syms.length > 0) {
-                  const sym = syms.shift();
-                  fallbackBatch.push({ ...ref, fromId: sym.id });
-                }
-              }
+              const fallbackBatch = assignRefsToSymbols2(entry.refs, symbolsWithIds);
               if (fallbackBatch.length > 0) store.insertRefsBatch(fallbackBatch);
             }
             store.upsertFile({
@@ -2650,19 +3197,23 @@ async function runIndexerWithStore(store, opts) {
               lastIndexed: Date.now()
             });
           } catch (innerErr) {
-            errors.push(`fallback write failed: ${entry.file}: ${innerErr instanceof Error ? innerErr.message : String(innerErr)}`);
+            errors.push(
+              `fallback write failed: ${entry.file}: ${innerErr instanceof Error ? innerErr.message : String(innerErr)}`
+            );
           }
         }
       }
     }
   }
-  if (discoveredFiles) {
+  if (discoveredFiles && discoveryComplete) {
     for (const [file_] of existingMeta) {
       if (!discoveredFiles.has(file_)) {
         store.deleteFile(file_);
       }
     }
   }
+  store.resolveRefs();
+  store.setMetadata("relation_graph_version", relationGraphVersion);
   const durationMs = Date.now() - startMs;
   store.setLastIndexed(Date.now());
   return {
@@ -2722,11 +3273,35 @@ function statsService(args) {
     store.close();
   }
 }
+function packageGraphService(args) {
+  const store = new IndexStore(args.projectRoot, { indexDir: args.indexDir });
+  try {
+    return store.getPackageGraph();
+  } finally {
+    store.close();
+  }
+}
+function fileGraphService(args) {
+  const store = new IndexStore(args.projectRoot, { indexDir: args.indexDir });
+  try {
+    return store.getFileGraph(args.packageFilter);
+  } finally {
+    store.close();
+  }
+}
+function symbolGraphService(args) {
+  const store = new IndexStore(args.projectRoot, { indexDir: args.indexDir });
+  try {
+    return store.getSymbolGraph(args.fileFilter);
+  } finally {
+    store.close();
+  }
+}
 
 // src/codebase-index/background-indexer.ts
 var DEFAULT_FULL_INDEX_TIMEOUT_MS = 24e4;
 var DEFAULT_INCREMENTAL_TIMEOUT_MS = 6e4;
-var DEFAULT_QUERY_TIMEOUT_MS = 8e3;
+var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var _ready = false;
 var _indexing = false;
 var _currentFile = 0;
@@ -2773,7 +3348,7 @@ function resolveWorkerUrl() {
   for (const rel of ["./worker.js", "./codebase-index/worker.js"]) {
     try {
       const url = new URL(rel, import.meta.url);
-      if (url.protocol === "file:" && fs7.existsSync(fileURLToPath(url))) return url;
+      if (url.protocol === "file:" && fs8.existsSync(fileURLToPath(url))) return url;
     } catch {
     }
   }
@@ -2804,14 +3379,22 @@ function ensureWorker() {
       if (!entry) return;
       pending.delete(msg.id);
       if (msg.ok) entry.resolve(msg.result);
-      else entry.reject(new Error(msg.error));
+      else {
+        const error = msg.errorName === "LockError" ? new LockError(msg.error) : new Error(msg.error);
+        if (msg.errorName && msg.errorName !== "Error") {
+          error.name = msg.errorName;
+        }
+        entry.reject(error);
+      }
     });
     w.on("error", (err) => {
+      if (worker !== w) return;
       worker = null;
       failAllPending(err);
     });
     w.on("exit", () => {
-      if (worker === w) worker = null;
+      if (worker !== w) return;
+      worker = null;
       failAllPending(new Error("codebase-index worker exited"));
     });
     worker = w;
@@ -2836,6 +3419,11 @@ function shutdownCodebaseIndexHost() {
 function callIndexOp(op, args, opts) {
   const w = ensureWorker();
   if (!w) return callInline(op, args, opts);
+  if (opts.signal?.aborted) {
+    return Promise.reject(
+      opts.signal.reason instanceof Error ? opts.signal.reason : new Error("Indexing cancelled")
+    );
+  }
   return new Promise((resolve2, reject) => {
     const id = nextRpcId++;
     const timer = setTimeout(() => {
@@ -2850,8 +3438,7 @@ function callIndexOp(op, args, opts) {
     const onAbort = () => {
       w.postMessage({ type: "cancel", id });
     };
-    if (opts.signal?.aborted) onAbort();
-    else opts.signal?.addEventListener("abort", onAbort, { once: true });
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
     const cleanup = () => {
       clearTimeout(timer);
       opts.signal?.removeEventListener("abort", onAbort);
@@ -3039,7 +3626,7 @@ var codebaseIndexTool = {
   category: "Project",
   icon: "index",
   description: "Build or incrementally update the project-wide symbol index. This powers fast codebase search and understanding. By default it only processes files that have changed since the last indexing run.",
-  usageHint: "IMPORTANT FOR LARGE CODEBASES:\n\n- First run (or after major changes): consider `force: true` for a clean rebuild.\n- Normal usage: call without arguments for fast incremental updates.\n- Use `langs` to restrict to specific languages if you only care about certain parts of the project.\nThis tool is relatively expensive \u2014 do not call it on every turn. Use it when the index is stale or before heavy codebase-search sessions.",
+  usageHint: "CREATE OR REFRESH THE SEARCH INDEX:\n\n- When `codebase-stats` or `codebase-search` reports no persisted index, call this without arguments, then retry the search.\n- Normal and first-time usage: call without arguments for an incremental build.\n- Use `force: true` only for a corrupt/stale index or an explicitly requested clean rebuild.\n- Use `langs` to restrict to specific languages if you only care about certain parts of the project.\nThis tool is relatively expensive \u2014 do not call it on every turn. Use it when the index is stale or before heavy codebase-search sessions.",
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write.outside-project"],
@@ -3095,12 +3682,14 @@ var codebaseSearchTool = {
   name: "codebase-search",
   category: "Project",
   icon: "index",
-  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Much more powerful and structured than raw `grep` for finding code by name or concept. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
-  usageHint: "PREFERRED FOR CODE UNDERSTANDING:\n\n- Use when you need to find where something is defined or used by name.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\nThis is generally better than `grep` when you are looking for symbols rather than arbitrary text patterns.",
+  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Prefer this before broad `tree`, `glob`, or `grep` exploration when finding code by name or concept. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
+  usageHint: "FIRST CHOICE FOR INDEXABLE CODE UNDERSTANDING:\n\n- Call before broad `tree`, `glob`, or `grep` exploration when locating symbols, concepts, definitions, or candidate modules.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\n- If `indexStatus` reports no persisted data, run `codebase-index` and retry.\nUse `grep` afterwards for exact text, regexes, unsupported content, or concrete usage sites.",
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
-  timeoutMs: 1e4,
+  // The index host has its own 30s read watchdog. Leave enough headroom for
+  // worker teardown and structured timeout reporting.
+  timeoutMs: 35e3,
   inputSchema: {
     type: "object",
     properties: {
@@ -3110,11 +3699,34 @@ var codebaseSearchTool = {
       },
       kind: {
         type: "string",
-        description: "Filter by symbol kind: class, function, interface, method, const, let, var, property, type, enum"
+        enum: [
+          "class",
+          "interface",
+          "enum",
+          "type",
+          "function",
+          "method",
+          "var",
+          "const",
+          "let",
+          "property",
+          "parameter",
+          "namespace",
+          "object",
+          "literal",
+          "schema",
+          "struct",
+          "trait",
+          "impl",
+          "static",
+          "mod"
+        ],
+        description: "Filter by indexed symbol kind"
       },
       lang: {
         type: "string",
-        description: "Filter by language: ts, tsx, js, jsx"
+        enum: ["ts", "tsx", "js", "jsx", "go", "py", "rs", "json", "yaml"],
+        description: "Filter by indexed language"
       },
       lspKind: {
         type: "integer",
@@ -3139,20 +3751,12 @@ var codebaseSearchTool = {
   },
   async execute(input, ctx, execOpts) {
     const state = getIndexState();
-    if (!state.ready) {
+    if (state.indexing && !state.ready) {
       return {
         results: [],
         total: 0,
         query: input.query,
-        indexStatus: state.indexing ? `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.` : "Index not yet built. The codebase is being indexed at startup \u2014 search will be available shortly."
-      };
-    }
-    if (state.indexing) {
-      return {
-        results: [],
-        total: 0,
-        query: input.query,
-        indexStatus: `Index refresh in progress (${state.currentFile}/${state.totalFiles} files). Results may be incomplete.`
+        indexStatus: `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.`
       };
     }
     if (state.lastError) {
@@ -3165,21 +3769,37 @@ var codebaseSearchTool = {
         indexStatus: `Index build failed: ${state.lastError}. ${retryHint}`
       };
     }
-    const limit = Math.min(input.limit ?? 20, 100);
+    const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 20), 100));
     const { results, total } = await searchCodebaseIndex(
       {
         projectRoot: ctx.projectRoot,
         indexDir: codebaseIndexDirOverride(ctx),
         query: input.query,
-        kind: input.kind,
-        lang: input.lang,
+        kind: input.kind?.toLowerCase(),
+        lang: input.lang?.toLowerCase(),
         file: input.file,
         lspKind: input.lspKind,
         limit
       },
       { signal: execOpts?.signal }
     );
-    return { results, total, query: input.query };
+    let hasPersistedIndex = state.ready || total > 0;
+    if (!hasPersistedIndex) {
+      try {
+        const stats = await codebaseIndexStats(
+          { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
+          { signal: execOpts?.signal }
+        );
+        hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
+      } catch {
+      }
+    }
+    return {
+      results,
+      total,
+      query: input.query,
+      ...hasPersistedIndex ? {} : { indexStatus: "No persisted index data found. Run codebase-index to build it." }
+    };
   }
 };
 
@@ -3188,12 +3808,15 @@ var codebaseStatsTool = {
   name: "codebase-stats",
   category: "Project",
   icon: "index",
-  description: "Return health and statistics about the current symbol index (total symbols, files, language/kind breakdown, size, last update). Useful to decide whether to re-index.",
-  usageHint: "CALL BEFORE HEAVY CODEBASE-SEARCH WORK:\n\n- Use to see if the index is up-to-date or needs a refresh.\n- No arguments required.\n- Helps avoid wasting tokens on searches against a stale index.\nLightweight and safe to call frequently.",
+  description: "Check whether a persisted codebase index exists and report its health and statistics (symbols, files, language/kind breakdown, size, last update).",
+  usageHint: "CHECK ONCE BEFORE BROAD CODE EXPLORATION:\n\n- Call before broad `tree`, `glob`, or `grep` exploration to see whether index-backed search is available.\n- If it reports no persisted data, run `codebase-index`, then use `codebase-search`.\n- No arguments required.\nLightweight and safe to call frequently.",
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
-  timeoutMs: 5e3,
+  // The index host has its own 30s read watchdog. Keep the outer tool budget
+  // longer so the host can return a structured timeout instead of being
+  // pre-empted by the generic tool executor.
+  timeoutMs: 35e3,
   inputSchema: {
     type: "object",
     properties: {},
@@ -3201,7 +3824,8 @@ var codebaseStatsTool = {
   },
   async execute(_input, ctx, execOpts) {
     const idxState = getIndexState();
-    if (!idxState.ready) {
+    const indexPath = resolveIndexDir(ctx.projectRoot, codebaseIndexDirOverride(ctx));
+    if (idxState.indexing) {
       return {
         totalSymbols: 0,
         totalFiles: 0,
@@ -3209,22 +3833,47 @@ var codebaseStatsTool = {
         byKind: {},
         lastIndexed: null,
         sizeBytes: 0,
-        indexPath: "",
+        indexPath,
         version: SCHEMA_VERSION,
-        indexStatus: idxState.indexing ? `Indexing in progress (${idxState.currentFile}/${idxState.totalFiles} files).` : "Index not yet built."
+        statsAvailable: false,
+        indexing: {
+          currentFile: idxState.currentFile,
+          totalFiles: idxState.totalFiles
+        },
+        indexStatus: idxState.ready ? `Index refresh in progress (${idxState.currentFile}/${idxState.totalFiles} files). The persisted snapshot remains available to codebase-search; retry stats after refresh.` : `Startup indexing in progress (${idxState.currentFile}/${idxState.totalFiles} files). Do not start another index; retry stats or codebase-search after completion.`
       };
     }
-    const stats = await codebaseIndexStats(
-      { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
-      { signal: execOpts?.signal }
-    );
-    if (idxState.indexing) {
+    let stats;
+    try {
+      stats = await codebaseIndexStats(
+        { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
+        { signal: execOpts?.signal }
+      );
+    } catch (err) {
+      if (!(err instanceof IndexTimeoutError) && err?.name !== "IndexTimeoutError") {
+        throw err;
+      }
       return {
-        ...stats,
-        indexStatus: `Index refresh in progress (${idxState.currentFile}/${idxState.totalFiles} files). Stats may be incomplete.`
+        totalSymbols: 0,
+        totalFiles: 0,
+        byLang: {},
+        byKind: {},
+        lastIndexed: null,
+        sizeBytes: 0,
+        indexPath,
+        version: SCHEMA_VERSION,
+        statsAvailable: false,
+        indexStatus: "Index statistics timed out. Do not repeatedly retry stats; try codebase-search directly or use the appropriate grep/glob/tree fallback."
       };
     }
     const circuit = idxState.circuit;
+    const hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
+    let indexStatus;
+    if (circuit.state === "open") {
+      indexStatus = `${hasPersistedIndex ? "Indexing" : "No persisted index data found, and indexing"} is paused after repeated failures (last: ${circuit.lastFailure ?? "unknown"}); auto-retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s, or run /codebase-reindex. ` + (hasPersistedIndex ? "Stats reflect the last successful build." : "Build the index after recovery.");
+    } else if (!hasPersistedIndex) {
+      indexStatus = "No persisted index data found. Run codebase-index to build it before broad code exploration.";
+    }
     return {
       totalSymbols: stats.totalSymbols,
       totalFiles: stats.totalFiles,
@@ -3234,9 +3883,8 @@ var codebaseStatsTool = {
       sizeBytes: stats.sizeBytes,
       indexPath: stats.indexPath,
       version: stats.version,
-      ...circuit.state === "open" ? {
-        indexStatus: `Indexing is paused after repeated failures (last: ${circuit.lastFailure ?? "unknown"}); auto-retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s, or run /codebase-reindex. Stats reflect the last successful build.`
-      } : {}
+      statsAvailable: true,
+      ...indexStatus ? { indexStatus } : {}
     };
   }
 };
@@ -3255,6 +3903,7 @@ export {
   codebaseSearchTool,
   codebaseStatsTool,
   enqueueReindex,
+  fileGraphService,
   getIndexState,
   indexCircuitBreaker,
   internalKindToLspKind,
@@ -3263,12 +3912,14 @@ export {
   isIndexing,
   lspKindToInternalKind,
   onIndexStateChange,
+  packageGraphService,
   resetIndexCircuitBreaker,
   resolveIndexDir,
   runIndexer,
   runStartupIndex,
   searchCodebaseIndex,
   shutdownCodebaseIndexHost,
+  symbolGraphService,
   tokenise
 };
 //# sourceMappingURL=index.js.map