@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/chunk-66A5ZFYA.js

@@ -0,0 +1,1758 @@
+import {
+  buildEmbeddingDiagnosis,
+  describeEmbeddingConfig,
+  renderChainSummary
+} from "./chunk-J4PMBXQQ.js";
+import {
+  runIndexHealthCheck
+} from "./chunk-2RTN2DFU.js";
+import {
+  IndexLockHeldError,
+  indexProjectParallel,
+  liveIndexLockHolder,
+  reindexFilesParallel,
+  wipeProjectData
+} from "./chunk-PJTNGD3Z.js";
+import {
+  Config
+} from "./chunk-UGR4QIGS.js";
+import {
+  makeProvenance
+} from "./chunk-UUNHHX4M.js";
+import {
+  resolveRowsFreshnessDetailed,
+  selectSampleFiles
+} from "./chunk-QLK6ED4Q.js";
+import {
+  BrainDatabase
+} from "./chunk-KLK3PBTO.js";
+import {
+  NON_CODE_LANGUAGES,
+  analysis_exclusions_exports,
+  isNonCodeLanguage
+} from "./chunk-SM7RFQRO.js";
+
+// src/intelligence/patterns/orphans.ts
+var ENGINE = "orphans@intelligence";
+var USAGE_TYPES = ["calls", "instantiates", "extends", "implements", "uses", "references", "imports", "overrides", "renders", "decorates", "mixes_in"];
+var MIN_EDGE_CONFIDENCE = 0.7;
+var SELF_LOOP_EXCLUDED = "selfLoop";
+var INFERRED_EXCLUDED = "inferred";
+var LOW_CONFIDENCE_EXCLUDED = "lowConfidence";
+var REPORTED_SYMBOL_TYPES = /* @__PURE__ */ new Set(["function", "method", "class", "interface", "struct", "enum"]);
+var CLASS_LIKE_TYPES = /* @__PURE__ */ new Set(["class", "interface", "struct", "enum"]);
+var MANIFEST_FILENAMES = /* @__PURE__ */ new Set([
+  "package.json",
+  "package-lock.json",
+  "tsconfig.json",
+  "jsconfig.json",
+  "composer.json",
+  "composer.lock",
+  "gemfile",
+  "gemfile.lock",
+  "rakefile",
+  "gemfile",
+  "cargo.toml",
+  "cargo.lock",
+  "go.mod",
+  "go.sum",
+  "requirements.txt",
+  "pipfile",
+  "pyproject.toml",
+  "setup.py",
+  "setup.cfg",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "settings.gradle",
+  "settings.gradle.kts",
+  "mix.exs",
+  "pubspec.yaml",
+  "pubspec.lock",
+  "cabal.project",
+  "stack.yaml",
+  "shard.yml",
+  "dune-project",
+  "dune",
+  "makefile",
+  "justfile",
+  "dockerfile",
+  "cmakelists.txt",
+  "deno.json",
+  "deno.jsonc",
+  "bun.lockb",
+  "pnpm-workspace.yaml"
+]);
+var ENTRY_POINT_NAMES = /* @__PURE__ */ new Set(["main", "__main__", "start", "run", "init", "setup", "handler", "default"]);
+var ENTRY_POINT_SUFFIXES = ["Handler", "Controller", "Middleware", "Route", "Routes", "Command", "Plugin"];
+var ENTRY_POINT_FILE_STEMS = /* @__PURE__ */ new Set(["index", "main", "app", "mod"]);
+function stemOf(relativePath2) {
+  const slash = relativePath2.lastIndexOf("/");
+  const base = slash >= 0 ? relativePath2.slice(slash + 1) : relativePath2;
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+function baseNameOf(relativePath2) {
+  const slash = relativePath2.lastIndexOf("/");
+  return slash >= 0 ? relativePath2.slice(slash + 1) : relativePath2;
+}
+function isEntryPointName(name) {
+  if (ENTRY_POINT_NAMES.has(name)) return true;
+  return ENTRY_POINT_SUFFIXES.some((s) => name.endsWith(s));
+}
+function isManifestFile(relativePath2) {
+  return MANIFEST_FILENAMES.has(baseNameOf(relativePath2).toLowerCase());
+}
+function posixJoin(dir, spec) {
+  const out = [];
+  for (const segment of ((dir === "" ? "" : dir + "/") + spec).split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (out.length > 0) out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join("/");
+}
+function isNonCodeFile(language) {
+  return isNonCodeLanguage(language);
+}
+function locFor(sym) {
+  return sym.lineEnd > sym.line ? sym.lineEnd - sym.line : 0;
+}
+async function detectOrphans(projectId, options = {}) {
+  const raw = await BrainDatabase.getRawInstance(projectId, { readonly: true });
+  const minConfidence = options.minConfidence ?? 0;
+  const maxResults = options.maxResults ?? 100;
+  const rules = new Set(options.rules ?? ["orphaned_function", "orphaned_class", "orphaned_file"]);
+  const includeTests = options.includeTests ?? false;
+  const files = raw.prepare(
+    "SELECT id, relative_path AS relativePath, language, line_count AS lineCount FROM brain_file WHERE project_id = ?"
+  ).all(projectId);
+  const fileById = new Map(files.map((f) => [f.id, f]));
+  const reportedTypes = [...REPORTED_SYMBOL_TYPES];
+  const symbols = raw.prepare(
+    "SELECT s.id, s.name, s.symbol_type AS symbolType, s.visibility, COALESCE(s.line_start,0) AS line, COALESCE(s.line_end,0) AS lineEnd, f.relative_path AS file, f.id AS fileId, f.language AS language, f.line_count AS fileLineCount FROM brain_symbol s JOIN brain_file f ON f.id = s.file_id WHERE s.project_id = ? AND s.symbol_type IN (" + reportedTypes.map(() => "?").join(",") + ")"
+  ).all(projectId, ...reportedTypes);
+  const typeParams = {};
+  const typeList = USAGE_TYPES.map((t, i) => {
+    typeParams[`t${i}`] = t;
+    return `@t${i}`;
+  }).join(",");
+  const usageFilter = `r.project_id = @projectId AND r.relationship_type IN (${typeList})`;
+  const GATE_SQL = `(CASE WHEN r.source_symbol_id IS NOT NULL AND r.target_symbol_id IS NOT NULL AND r.source_symbol_id = r.target_symbol_id THEN '${SELF_LOOP_EXCLUDED}' WHEN r.evidence_class = 'inferred' THEN '${INFERRED_EXCLUDED}' WHEN r.confidence < @minConf THEN '${LOW_CONFIDENCE_EXCLUDED}' ELSE NULL END)`;
+  const CLEAN_SQL = `${GATE_SQL} IS NULL`;
+  const BIND = { projectId, minConf: MIN_EDGE_CONFIDENCE, ...typeParams };
+  const NOT_SELF_LOOP_SQL = `(r.target_symbol_id IS NOT NULL AND (r.source_symbol_id IS NULL OR r.source_symbol_id <> r.target_symbol_id))`;
+  const usedIds = /* @__PURE__ */ new Set();
+  const usedNames = /* @__PURE__ */ new Set();
+  const fileIncomingUsage = /* @__PURE__ */ new Map();
+  const symbolsWithAnyIncoming = /* @__PURE__ */ new Set();
+  const rejectedFor = /* @__PURE__ */ new Map();
+  const edgeRejects = { [SELF_LOOP_EXCLUDED]: 0, [INFERRED_EXCLUDED]: 0, [LOW_CONFIDENCE_EXCLUDED]: 0 };
+  const edgeRejectsByType = {};
+  {
+    const rows = raw.prepare(
+      `SELECT r.relationship_type AS rt, ${GATE_SQL} AS reason, r.target_symbol_id AS id, COUNT(*) AS n FROM brain_relationship r WHERE ${usageFilter} AND ${GATE_SQL} IS NOT NULL GROUP BY r.relationship_type, reason, r.target_symbol_id`
+    ).all(BIND);
+    for (const row of rows) {
+      edgeRejects[row.reason] += row.n;
+      const bucket = edgeRejectsByType[row.rt] ??= {};
+      bucket[row.reason] = (bucket[row.reason] ?? 0) + row.n;
+      if (row.id) {
+        const entry = rejectedFor.get(row.id) ?? { rows: 0, reasons: [] };
+        entry.rows += row.n;
+        if (!entry.reasons.includes(row.reason)) entry.reasons.push(row.reason);
+        rejectedFor.set(row.id, entry);
+      }
+    }
+  }
+  {
+    const rows = raw.prepare(
+      `SELECT r.target_symbol_id AS id, MAX(CASE WHEN ${CLEAN_SQL} AND r.source_symbol_id IS NOT NULL THEN 1 ELSE 0 END) AS used, MAX(CASE WHEN r.source_symbol_id IS NOT NULL AND r.target_symbol_id IS NOT NULL AND r.source_symbol_id <> r.target_symbol_id THEN 1 ELSE 0 END) AS incoming FROM brain_relationship r WHERE ${usageFilter} AND r.target_symbol_id IS NOT NULL GROUP BY r.target_symbol_id`
+    ).all(BIND);
+    for (const row of rows) {
+      if (row.used) usedIds.add(row.id);
+      if (row.incoming) symbolsWithAnyIncoming.add(row.id);
+    }
+  }
+  {
+    const leafName = (value) => {
+      const afterColon = value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;
+      const dot = afterColon.lastIndexOf(".");
+      return dot > 0 ? afterColon.slice(dot + 1) : afterColon;
+    };
+    const externals = raw.prepare(
+      `SELECT DISTINCT r.target_external AS ext FROM brain_relationship r WHERE ${usageFilter} AND ${CLEAN_SQL} AND r.target_external IS NOT NULL`
+    ).all(BIND);
+    for (const row of externals) usedNames.add(leafName(row.ext));
+    const names = raw.prepare(
+      `SELECT DISTINCT t.name AS name FROM brain_relationship r JOIN brain_symbol t ON t.id = r.target_symbol_id WHERE ${usageFilter} AND ${CLEAN_SQL} AND r.source_symbol_id IS NULL`
+    ).all(BIND);
+    for (const row of names) usedNames.add(row.name);
+  }
+  {
+    const rows = raw.prepare(
+      `SELECT t.file_id AS f, COUNT(*) AS edges, COUNT(DISTINCT COALESCE(r.source_symbol_id, '?')) AS sources FROM brain_relationship r JOIN brain_symbol t ON t.id = r.target_symbol_id WHERE ${usageFilter} AND ${NOT_SELF_LOOP_SQL} AND t.file_id IS NOT NULL GROUP BY t.file_id`
+    ).all(BIND);
+    for (const row of rows) fileIncomingUsage.set(row.f, { edges: row.edges, sources: row.sources });
+  }
+  const referencedFiles = /* @__PURE__ */ new Set();
+  {
+    const rows = raw.prepare(
+      `SELECT DISTINCT t.file_id AS f FROM brain_relationship r JOIN brain_symbol s ON s.id = r.source_symbol_id JOIN brain_symbol t ON t.id = r.target_symbol_id WHERE ${usageFilter} AND ${CLEAN_SQL} AND s.file_id IS NOT NULL AND t.file_id IS NOT NULL AND s.file_id <> t.file_id`
+    ).all(BIND);
+    for (const row of rows) referencedFiles.add(row.f);
+  }
+  const ambiguousNames = /* @__PURE__ */ new Set();
+  {
+    const nameCounts = /* @__PURE__ */ new Map();
+    for (const symbol of symbols) nameCounts.set(symbol.name, (nameCounts.get(symbol.name) ?? 0) + 1);
+    for (const [name, count] of nameCounts) if (count > 1) ambiguousNames.add(name);
+  }
+  const importReferencedFiles = /* @__PURE__ */ new Set();
+  const importUnattributedStems = /* @__PURE__ */ new Set();
+  let importRowsSeen = 0;
+  let importRowsResolved = 0;
+  let importRowsUnattributed = 0;
+  {
+    const indexedPaths = /* @__PURE__ */ new Set();
+    const fileDirById = /* @__PURE__ */ new Map();
+    const fileIdByPath = /* @__PURE__ */ new Map();
+    for (const f of files) {
+      indexedPaths.add(f.relativePath);
+      fileIdByPath.set(f.relativePath, f.id);
+      const slash = f.relativePath.lastIndexOf("/");
+      fileDirById.set(f.id, slash > 0 ? f.relativePath.slice(0, slash) : "");
+    }
+    const RESOLVABLE_SUFFIXES = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rb", ".go", ".rs", ".lua", ".ex", ".exs", ".clj", ".java", ".kt", ".c", ".h", ".cpp", ".cs", ".php", ".pl", ".sh", ".erl", ".jl", ".swift", ".scala", ".json", ".yaml", ".yml", ".toml", ".md"];
+    const INDEX_STEMS = ["index", "mod", "init", "__init__"];
+    const resolveAgainst = (spec, importerDir) => {
+      const bases = spec.startsWith(".") ? [importerDir] : [""];
+      for (const base of bases) {
+        const joined = posixJoin(base, spec);
+        for (const suffix of RESOLVABLE_SUFFIXES) {
+          const candidate = joined + suffix;
+          if (indexedPaths.has(candidate)) return candidate;
+        }
+        for (const stem of INDEX_STEMS) {
+          for (const suffix of RESOLVABLE_SUFFIXES) {
+            if (!suffix) continue;
+            const candidate = joined + "/" + stem + suffix;
+            if (indexedPaths.has(candidate)) return candidate;
+          }
+        }
+      }
+      return null;
+    };
+    const importTargets = raw.prepare(
+      "SELECT r.target_external AS ext, r.source_symbol_id AS src, s.file_id AS srcFile FROM brain_relationship r LEFT JOIN brain_symbol s ON s.id = r.source_symbol_id WHERE r.project_id = ? AND r.relationship_type = 'imports'"
+    ).all(projectId);
+    for (const row of importTargets) {
+      if (!row.ext) continue;
+      importRowsSeen++;
+      const spec = row.ext.includes(":") ? row.ext.slice(0, row.ext.indexOf(":")) : row.ext;
+      const importerDir = row.srcFile ? fileDirById.get(row.srcFile) : void 0;
+      if (importerDir === void 0) {
+        importRowsUnattributed++;
+        const stem = stemOf(spec);
+        if (stem) importUnattributedStems.add(stem);
+        continue;
+      }
+      const resolved = resolveAgainst(spec, importerDir);
+      if (resolved === null) continue;
+      importRowsResolved++;
+      const resolvedId = fileIdByPath.get(resolved);
+      if (resolvedId && resolvedId !== row.srcFile) importReferencedFiles.add(resolvedId);
+    }
+  }
+  const uniqueFileStems = /* @__PURE__ */ new Set();
+  {
+    const stemCounts = /* @__PURE__ */ new Map();
+    for (const f of files) {
+      const stem = stemOf(f.relativePath);
+      stemCounts.set(stem, (stemCounts.get(stem) ?? 0) + 1);
+    }
+    for (const [stem, count] of stemCounts) if (count === 1) uniqueFileStems.add(stem);
+  }
+  const importedBySomething = (fileId, relativePath2) => {
+    if (importReferencedFiles.has(fileId)) return true;
+    if (importUnattributedStems.size === 0) return false;
+    const stem = stemOf(relativePath2);
+    return uniqueFileStems.has(stem) && importUnattributedStems.has(stem);
+  };
+  const suppressed = {
+    testPath: 0,
+    hardNoise: 0,
+    noiseSymbolName: 0,
+    entryPointName: 0,
+    nonCodeFile: 0,
+    manifestFile: 0,
+    ruleNotRequested: 0,
+    belowMinConfidence: 0
+  };
+  const testPathMemo = /* @__PURE__ */ new Map();
+  const noisePathMemo = /* @__PURE__ */ new Map();
+  const isTestFile = (p) => {
+    let v = testPathMemo.get(p);
+    if (v === void 0) {
+      v = analysis_exclusions_exports.isTestPath(p);
+      testPathMemo.set(p, v);
+    }
+    return v;
+  };
+  const isNoiseFile = (p) => {
+    let v = noisePathMemo.get(p);
+    if (v === void 0) {
+      v = analysis_exclusions_exports.isHardNoisePath(p);
+      noisePathMemo.set(p, v);
+    }
+    return v;
+  };
+  const candidates = [];
+  const buildSymbolFinding = (sym, confidence, fileReferenced, nameAmbiguous, rejected, fileUsage) => {
+    const classLike = CLASS_LIKE_TYPES.has(sym.symbolType);
+    const rule = classLike ? "orphaned_class" : "orphaned_function";
+    return {
+      rule,
+      engine: ENGINE,
+      severity: "info",
+      confidence,
+      location: { file: sym.file, line: sym.line, symbol: sym.name },
+      linesOfCode: locFor(sym),
+      description: `${classLike ? "Type" : "Function"} '${sym.name}' has no incoming ${USAGE_TYPES.join("/")} relationship.`,
+      remediation: "Verify it is not referenced dynamically, via reflection, framework registration, or build/test config before considering removal.",
+      evidence: [
+        { kind: "relationship", description: `No resolved incoming relationship of type ${USAGE_TYPES.join("/")} names this symbol id. (contains/exports are indexer bookkeeping and are not usage.)` },
+        { kind: "reference", description: nameAmbiguous ? `No name-matched reference either, but '${sym.name}' is declared ${2}+ times in the reporting scope, so a name reference could not have been attributed to this declaration. Candidates in this class measured 14.4% false positive against 0.0% for unambiguous names.` : `No name-matched cross-file reference (target_external) names this symbol, and its name is declared exactly once in the reporting scope, so a name reference would have been decisive if one existed.` },
+        { kind: "heuristic", description: fileReferenced ? `Its file IS reached from other files by a resolved cross-file edge, which correlates with a higher false-positive rate (11.4% vs 3.7% measured across a 9-repository corpus): a reachable file is where an unrecorded reference is most likely.` : `Its file has no incoming cross-file reference at all, which correlates with a lower false-positive rate (3.7% measured).` },
+        ...rejected !== void 0 ? [{
+          kind: "heuristic",
+          description: `REFUSED EVIDENCE: ${rejected.rows} row(s) about this symbol were excluded as unverified (${rejected.reasons.join(", ")}). A row like that is not proof of a consumer \u2014 on rake an \`overrides\` row that is simultaneously a self-loop, evidenceClass "inferred" and published at 0.5 was the only thing standing between \`listen\` in lib/Mojo/IOLoop/Server.pm and this report, and that symbol has no recorded callers at all. If you believe the excluded row, the declaring ancestor or caller is outside the indexed files and the analyzer did not capture it; this finding is then a coverage gap, not dead code.`
+        }] : [],
+        ...fileUsage ? [{
+          kind: "heuristic",
+          description: `COVERAGE GAP INDICATOR: this symbol has no incoming usage edge at all, but its file receives ${fileUsage.edges} incoming usage edge(s) from ${fileUsage.sources} distinct source(s). The analyzer reached this file and recorded its other members; it did not record this one. That asymmetry is the signature of a missing reference rather than of an unused declaration, and it is why this finding should be checked against the source before anything is removed.`
+        }] : []
+      ],
+      limitations: [
+        "Name-only matching cannot see dynamic dispatch, reflection, or string-based lookups.",
+        ...rejected !== void 0 ? [`${rejected.rows} relationship row(s) about this symbol were excluded as unverified. If the analyzer failed to capture a real caller, this finding is a coverage gap rather than dead code; the excluded rows are itemised in the evidence above.`] : [],
+        ...fileUsage ? [`This symbol has no recorded incoming reference while its file has ${fileUsage.edges} from ${fileUsage.sources} source(s), so the absence of evidence here is probably the analyzer's, not the code's. Verify against the source before acting on it.`] : [],
+        ...nameAmbiguous ? [`The name '${sym.name}' is declared more than once; unresolved name-only references are treated as uncertain and do not suppress this candidate.`] : [],
+        "Framework entry points not matched by the built-in name/suffix rules may be false positives.",
+        "Build configs, plugin manifests (XML), and test conventions are not scanned."
+      ]
+    };
+  };
+  const buildFileFinding = (row, confidence) => {
+    const hasSymbols = symbols.some((s) => s.fileId === row.id);
+    return {
+      rule: "orphaned_file",
+      engine: ENGINE,
+      severity: "info",
+      confidence,
+      location: { file: row.relativePath, line: 1 },
+      linesOfCode: row.lineCount ?? 0,
+      description: `File '${row.relativePath}' has no incoming references from other files (no cross-file symbol usage, and no import specifier agreeing with its path).`,
+      remediation: "Confirm the file is not an entry point, dynamically loaded, or referenced by build/test tooling before removal.",
+      evidence: [
+        { kind: "relationship", description: "No resolved cross-file usage relationship lands in this file." },
+        { kind: "import", description: `No import specifier resolves to this file. The index attributed ${importRowsResolved} of ${importRowsSeen} import row(s) to a source file and resolved ${importReferencedFiles.size} target file(s); ${importRowsUnattributed} row(s) could not be attributed and fell back to a stem match, which applies only to a stem naming exactly one file in the project.` },
+        { kind: "heuristic", description: importRowsSeen > 0 ? `The import channel was available as evidence (${importRowsSeen} row(s), ${importRowsUnattributed} unattributable).` : `The index records NO import relationships, so the only evidence channel available was cross-file symbol usage.` }
+      ],
+      limitations: [
+        "Entry points and dynamically loaded files may appear orphaned.",
+        "Build systems and non-code manifests are not scanned.",
+        "An import cannot be attributed to the file that made it in this index, so a name collision inside a package cannot be used to clear a file.",
+        ...hasSymbols ? [] : ["This file contributed no reportable symbols, so the cross-file symbol channel had nothing to match on."]
+      ]
+    };
+  };
+  for (const sym of symbols) {
+    if (!includeTests && isTestFile(sym.file)) {
+      suppressed.testPath++;
+      continue;
+    }
+    if (isNoiseFile(sym.file)) {
+      suppressed.hardNoise++;
+      continue;
+    }
+    if (analysis_exclusions_exports.isNoiseSymbolName(sym.name)) {
+      suppressed.noiseSymbolName++;
+      continue;
+    }
+    if (isEntryPointName(sym.name)) {
+      suppressed.entryPointName++;
+      continue;
+    }
+    if (isNonCodeFile(sym.language)) {
+      suppressed.nonCodeFile++;
+      continue;
+    }
+    const used = usedIds.has(sym.id) || usedNames.has(sym.name) && !ambiguousNames.has(sym.name);
+    if (used) continue;
+    const rule = CLASS_LIKE_TYPES.has(sym.symbolType) ? "orphaned_class" : "orphaned_function";
+    if (!rules.has(rule)) {
+      suppressed.ruleNotRequested++;
+      continue;
+    }
+    const nameAmbiguous = ambiguousNames.has(sym.name);
+    const fileReferenced = referencedFiles.has(sym.fileId);
+    let confidence = 0.5;
+    confidence += nameAmbiguous ? -0.15 : 0.15;
+    confidence += fileReferenced ? -0.05 : 0.05;
+    if (confidence < 0.3) confidence = 0.3;
+    if (confidence > 0.7) confidence = 0.7;
+    if (confidence < minConfidence) {
+      suppressed.belowMinConfidence++;
+      continue;
+    }
+    const fileUsage = symbolsWithAnyIncoming.has(sym.id) ? void 0 : fileIncomingUsage.get(sym.fileId);
+    candidates.push({ conf: confidence, file: sym.file, loc: locFor(sym), symbol: sym, rejected: rejectedFor.get(sym.id), fileUsage });
+  }
+  const fileScope = /* @__PURE__ */ new Set();
+  if (rules.has("orphaned_file")) {
+    for (const file of files) {
+      if (!includeTests && isTestFile(file.relativePath)) continue;
+      if (isNoiseFile(file.relativePath)) continue;
+      if (isManifestFile(file.relativePath)) {
+        suppressed.manifestFile++;
+        continue;
+      }
+      const stem = stemOf(file.relativePath);
+      if (ENTRY_POINT_FILE_STEMS.has(stem.toLowerCase())) continue;
+      fileScope.add(file.id);
+      const referencedBySymbol = referencedFiles.has(file.id);
+      if (referencedBySymbol || importedBySomething(file.id, file.relativePath)) continue;
+      let confidence = importRowsSeen > 0 ? 0.5 : 0.3;
+      if (isNonCodeFile(file.language)) confidence += 0.05;
+      if (confidence < minConfidence) {
+        suppressed.belowMinConfidence++;
+        continue;
+      }
+      candidates.push({ conf: confidence, file: file.relativePath, loc: file.lineCount ?? 0, fileRow: file });
+    }
+  } else {
+    for (const sym of symbols) if (!isTestFile(sym.file) && !isNoiseFile(sym.file)) fileScope.add(sym.fileId);
+  }
+  candidates.sort((a, b) => b.conf - a.conf || b.loc - a.loc || a.file.localeCompare(b.file));
+  const truncated = candidates.length > maxResults;
+  const page = candidates.slice(0, maxResults).map(
+    (c) => c.symbol ? buildSymbolFinding(c.symbol, c.conf, referencedFiles.has(c.symbol.fileId), ambiguousNames.has(c.symbol.name), c.rejected, c.fileUsage) : buildFileFinding(c.fileRow, c.conf)
+  );
+  const byRule = {};
+  for (const f of page) byRule[f.rule] = (byRule[f.rule] ?? 0) + 1;
+  const candidatesByRule = {};
+  let candidatesConfidenceSum = 0;
+  for (const c of candidates) {
+    const rule = c.symbol ? CLASS_LIKE_TYPES.has(c.symbol.symbolType) ? "orphaned_class" : "orphaned_function" : "orphaned_file";
+    candidatesByRule[rule] = (candidatesByRule[rule] ?? 0) + 1;
+    candidatesConfidenceSum += c.conf;
+  }
+  return {
+    findings: page,
+    provenance: makeProvenance({
+      evidenceClass: "static_finding",
+      engine: ENGINE,
+      engineVersion: "m10.03",
+      projectId,
+      source: "brain_symbol+brain_relationship+brain_file",
+      limitations: [
+        "Dynamic dispatch, reflection, string references, and external manifests are not fully observable.",
+        ...ambiguousNames.size ? [`${ambiguousNames.size} duplicate symbol name(s) in the reporting scope were treated as ambiguous rather than globally resolved.`] : [],
+        ...importRowsSeen === 0 ? ["The index records no import relationships, so file-level findings rest on the cross-file symbol channel alone."] : [],
+        ...importRowsUnattributed > 0 ? [`${importRowsUnattributed} of ${importRowsSeen} import row(s) name no source file, so they could only be matched by stem; a stem shared by two or more files carries no path evidence and was ignored.`] : [],
+        `Non-code files (${[...NON_CODE_LANGUAGES].slice(0, 6).join(", ")}, ...) contribute no symbol candidates; they are still indexed and still checked as whole files.`
+      ],
+      truncated
+    }),
+    summary: {
+      total: page.length,
+      byRule,
+      scannedSymbols: symbols.length,
+      scannedFiles: fileScope.size,
+      truncated,
+      candidatesTotal: candidates.length,
+      candidatesByRule,
+      candidatesAverageConfidence: candidates.length ? candidatesConfidenceSum / candidates.length : 0,
+      // New: why the candidate set is the size it is. Every number the scan
+      // discarded, so "the tool found nothing" is distinguishable from "the
+      // tool suppressed everything it saw".
+      suppressedByReason: suppressed,
+      // How much usage evidence the scan refused to believe, and why. The
+      // orphan page is the product of what is believed, so the volume that was
+      // NOT believed is part of the result and is reported with it. These rows
+      // are the index's own published confidence and evidence class, so the
+      // numbers are the analyzer's, not this tool's opinion of them.
+      unverifiedUsageEdges: {
+        total: edgeRejects[SELF_LOOP_EXCLUDED] + edgeRejects[INFERRED_EXCLUDED] + edgeRejects[LOW_CONFIDENCE_EXCLUDED],
+        byReason: {
+          [SELF_LOOP_EXCLUDED]: edgeRejects[SELF_LOOP_EXCLUDED],
+          [INFERRED_EXCLUDED]: edgeRejects[INFERRED_EXCLUDED],
+          [LOW_CONFIDENCE_EXCLUDED]: edgeRejects[LOW_CONFIDENCE_EXCLUDED]
+        },
+        byRelationshipType: edgeRejectsByType,
+        minimumConfidence: MIN_EDGE_CONFIDENCE
+      },
+      importResolution: {
+        rowsSeen: importRowsSeen,
+        attributedToASourceFile: importRowsSeen - importRowsUnattributed,
+        unattributed: importRowsUnattributed,
+        resolvedToAFile: importRowsResolved,
+        filesClearedByImport: importReferencedFiles.size
+      }
+    }
+  };
+}
+
+// src/ast/tools.ts
+var BrainTools;
+((BrainTools2) => {
+  async function searchCode(projectId, query, options = {}) {
+    const { searchSymbols } = await import("./symbol-search-KB4MU4SI.js");
+    return searchSymbols(projectId, query, options);
+  }
+  BrainTools2.searchCode = searchCode;
+})(BrainTools || (BrainTools = {}));
+var PatternBrainTools;
+((PatternBrainTools2) => {
+  async function detectPatterns(projectId, options = {}) {
+    const opts = {
+      includeOrphaned: true,
+      includeFramework: true,
+      includeAntiPatterns: true,
+      confidenceThreshold: 0.5,
+      maxResults: 200,
+      ...options
+    };
+    const patterns = [];
+    let orphanCandidates = 0;
+    const orphanByType = {};
+    let orphanConfidenceSum = 0;
+    if (opts.includeOrphaned) {
+      const orphanReport = await detectOrphans(projectId, {
+        minConfidence: opts.confidenceThreshold,
+        maxResults: opts.maxResults
+      });
+      for (const finding of orphanReport.findings) {
+        patterns.push({
+          type: finding.rule,
+          confidence: finding.confidence,
+          location: { file: finding.location.file, line: finding.location.line, symbol: finding.location.symbol },
+          description: finding.description,
+          severity: "info",
+          suggestion: finding.remediation,
+          evidence: finding.evidence.map((ev) => ({ type: ev.kind, description: ev.description }))
+        });
+      }
+      orphanCandidates = orphanReport.summary.candidatesTotal;
+      for (const [k, v] of Object.entries(orphanReport.summary.candidatesByRule)) orphanByType[k] = (orphanByType[k] ?? 0) + v;
+      orphanConfidenceSum = orphanReport.summary.candidatesAverageConfidence * orphanCandidates;
+    }
+    const { detectIndexRules } = await import("./rules-I453JTRC.js");
+    const ruleFindings = await detectIndexRules(projectId, {
+      confidenceThreshold: opts.confidenceThreshold,
+      maxResults: opts.maxResults,
+      includeFramework: opts.includeFramework,
+      includeAntiPatterns: opts.includeAntiPatterns
+    });
+    for (const finding of ruleFindings) patterns.push(finding);
+    const severityRank = { error: 0, warning: 1, info: 2 };
+    const orphanPage = patterns.filter((p) => String(p.type).startsWith("orphaned_"));
+    const rulePage = patterns.filter((p) => !String(p.type).startsWith("orphaned_"));
+    patterns.length = 0;
+    const ranked = [...orphanPage, ...rulePage].sort((a, b) => {
+      if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+      const sa = severityRank[a.severity] ?? 3;
+      const sb = severityRank[b.severity] ?? 3;
+      if (sa !== sb) return sa - sb;
+      return String(a.location?.file ?? "").localeCompare(String(b.location?.file ?? ""));
+    });
+    patterns.push(...ranked);
+    const byType = { ...orphanByType };
+    const bySeverity = {};
+    for (const k of Object.keys(orphanByType)) bySeverity["info"] = (bySeverity["info"] ?? 0) + orphanByType[k];
+    let confidenceSum = orphanConfidenceSum;
+    let ruleFindingCount = 0;
+    for (const pattern of patterns) {
+      if (String(pattern.type).startsWith("orphaned_")) continue;
+      ruleFindingCount++;
+      byType[pattern.type] = (byType[pattern.type] || 0) + 1;
+      bySeverity[pattern.severity] = (bySeverity[pattern.severity] || 0) + 1;
+      confidenceSum += pattern.confidence;
+    }
+    const REQUESTED = [
+      { on: opts.includeOrphaned !== false, match: (t) => t.startsWith("orphaned_") },
+      { on: opts.includeFramework !== false, match: (t) => t === "framework-detected" },
+      {
+        on: opts.includeAntiPatterns !== false,
+        match: (t) => ["high-complexity-function", "long-parameter-list", "god-class"].includes(t)
+      }
+    ];
+    const page = patterns.slice(0, opts.maxResults);
+    if (patterns.length > opts.maxResults && page.length > 0) {
+      for (const req of REQUESTED) {
+        if (!req.on) continue;
+        const onPage = page.some((p) => req.match(String(p.type)));
+        if (onPage) continue;
+        const best = patterns.find((p) => req.match(String(p.type)));
+        if (!best) continue;
+        let victim = -1;
+        for (let i = page.length - 1; i >= 0; i--) {
+          const others = REQUESTED.filter((r) => r.on && r.match(String(page[i].type)));
+          if (others.length > 1) continue;
+          if (page.filter((p, j) => j < i && others.some((r) => r.match(String(p.type)))).length > 0) continue;
+          victim = i;
+          break;
+        }
+        if (victim === -1) continue;
+        page[victim] = best;
+      }
+      page.sort((a, b) => {
+        if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+        const sa = severityRank[a.severity] ?? 3;
+        const sb = severityRank[b.severity] ?? 3;
+        if (sa !== sb) return sa - sb;
+        return String(a.location?.file ?? "").localeCompare(String(b.location?.file ?? ""));
+      });
+    }
+    const displayedPatterns = page;
+    const censusTotal = orphanCandidates + ruleFindingCount;
+    return {
+      patterns: displayedPatterns,
+      statistics: {
+        // The census, not the page. This field was the returned page's length
+        // while byType / bySeverity / averageConfidence beside it all described
+        // the census, so one object reported two different universes and the
+        // handler printed the page length under the words "patterns (N)".
+        // With a default limit of 20 the tool fetched 100, printed 20, and
+        // reported 100. `scan.displayed` is the page length.
+        totalFound: censusTotal,
+        byType,
+        bySeverity,
+        averageConfidence: censusTotal > 0 ? confidenceSum / censusTotal : 0
+      },
+      recommendations: [],
+      scan: {
+        candidatesEvaluated: censusTotal,
+        findingsBeforeDisplayLimit: censusTotal,
+        displayed: displayedPatterns.length,
+        truncated: censusTotal > displayedPatterns.length
+      }
+    };
+  }
+  PatternBrainTools2.detectPatterns = detectPatterns;
+})(PatternBrainTools || (PatternBrainTools = {}));
+
+// src/intelligence/health/health-provider.ts
+import { relative as relativePath, resolve, isAbsolute, sep } from "path";
+import { statSync } from "fs";
+
+// src/intelligence/analysis/run-history.ts
+import { createHash, randomUUID } from "crypto";
+var ENGINE_VERSION = "m10.04";
+var STATES = ["open", "resolved", "suppressed", "reopened", "mitigated", "stale"];
+var STATE_ORDER = { open: 0, reopened: 1, mitigated: 2, stale: 3, suppressed: 4, resolved: 5 };
+function now() {
+  return Date.now();
+}
+function json(value) {
+  return JSON.stringify(value ?? null);
+}
+function parseJson(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string") return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function parseJsonStringArray(value) {
+  const list = parseJson(value);
+  return list.filter((item) => typeof item === "string");
+}
+function hash(value) {
+  return createHash("sha256").update(json(value)).digest("hex");
+}
+function stateOf(value) {
+  return typeof value === "string" && STATES.includes(value) ? value : "open";
+}
+function ensureColumn(raw, table, name, ddl) {
+  const columns = raw.prepare(`PRAGMA table_info(${table})`).all();
+  if (columns.some((col) => col.name === name)) return;
+  raw.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${ddl}`);
+}
+function ensureHistorySchema(raw) {
+  raw.exec(`
+    CREATE TABLE IF NOT EXISTS brain_analysis_run (
+      id TEXT PRIMARY KEY NOT NULL, project_id TEXT NOT NULL, kind TEXT NOT NULL,
+      status TEXT NOT NULL, engine_version TEXT NOT NULL, input_hash TEXT NOT NULL,
+      started_at INTEGER NOT NULL, completed_at INTEGER, finding_count INTEGER NOT NULL DEFAULT 0,
+      error TEXT, time_created INTEGER NOT NULL, time_updated INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS brain_analysis_finding (
+      id TEXT PRIMARY KEY NOT NULL, project_id TEXT NOT NULL, kind TEXT NOT NULL,
+      fingerprint TEXT NOT NULL, rule TEXT NOT NULL, title TEXT NOT NULL, severity TEXT NOT NULL,
+      state TEXT NOT NULL, confidence REAL, evidence TEXT,
+      location TEXT, limitations TEXT, evidence_class TEXT, engine TEXT, engine_version TEXT,
+      first_seen_at INTEGER NOT NULL,
+      last_seen_at INTEGER NOT NULL, resolved_at INTEGER, suppressed_at INTEGER, mitigated_at INTEGER,
+      occurrence_count INTEGER NOT NULL DEFAULT 0, time_created INTEGER NOT NULL, time_updated INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS brain_analysis_occurrence (
+      id TEXT PRIMARY KEY NOT NULL, finding_id TEXT NOT NULL, run_id TEXT NOT NULL, state TEXT NOT NULL,
+      location TEXT, evidence TEXT, limitations TEXT, evidence_class TEXT, engine TEXT, engine_version TEXT,
+      observed_at INTEGER NOT NULL, time_created INTEGER NOT NULL, time_updated INTEGER NOT NULL
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS brain_analysis_finding_identity_idx ON brain_analysis_finding(project_id, kind, fingerprint);
+    CREATE INDEX IF NOT EXISTS brain_analysis_run_project_idx ON brain_analysis_run(project_id);
+    CREATE INDEX IF NOT EXISTS brain_analysis_run_kind_idx ON brain_analysis_run(kind);
+    CREATE INDEX IF NOT EXISTS brain_analysis_run_started_idx ON brain_analysis_run(started_at);
+    CREATE INDEX IF NOT EXISTS brain_analysis_finding_project_idx ON brain_analysis_finding(project_id);
+    CREATE INDEX IF NOT EXISTS brain_analysis_finding_state_idx ON brain_analysis_finding(project_id, state);
+    CREATE INDEX IF NOT EXISTS brain_analysis_occurrence_finding_idx ON brain_analysis_occurrence(finding_id);
+    CREATE INDEX IF NOT EXISTS brain_analysis_occurrence_run_idx ON brain_analysis_occurrence(run_id);
+  `);
+  ensureColumn(raw, "brain_analysis_finding", "location", "TEXT");
+  ensureColumn(raw, "brain_analysis_finding", "limitations", "TEXT");
+  ensureColumn(raw, "brain_analysis_finding", "evidence_class", "TEXT");
+  ensureColumn(raw, "brain_analysis_finding", "engine", "TEXT");
+  ensureColumn(raw, "brain_analysis_finding", "engine_version", "TEXT");
+  ensureColumn(raw, "brain_analysis_occurrence", "limitations", "TEXT");
+  ensureColumn(raw, "brain_analysis_occurrence", "evidence_class", "TEXT");
+  ensureColumn(raw, "brain_analysis_occurrence", "engine", "TEXT");
+  ensureColumn(raw, "brain_analysis_occurrence", "engine_version", "TEXT");
+}
+function fingerprintFinding(kind, input) {
+  return input.fingerprint ?? hash({ kind, rule: input.rule, title: input.title, location: input.location ?? null, evidence: input.evidence ?? [], limitations: input.limitations ?? [], evidenceClass: input.evidenceClass ?? null, engine: input.engine ?? null, engineVersion: input.engineVersion ?? null });
+}
+function readRun(row) {
+  return { id: row.id, projectId: row.project_id, kind: row.kind, status: row.status, engineVersion: row.engine_version, inputHash: row.input_hash, startedAt: row.started_at, completedAt: row.completed_at ?? null, findingCount: row.finding_count, error: row.error ?? null };
+}
+function readFinding(row) {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    kind: row.kind,
+    fingerprint: row.fingerprint,
+    rule: row.rule,
+    title: row.title,
+    severity: row.severity,
+    state: stateOf(row.state),
+    confidence: row.confidence ?? null,
+    evidence: parseJson(row.evidence),
+    location: row.location ?? null,
+    limitations: parseJsonStringArray(row.limitations),
+    evidenceClass: row.evidence_class ?? null,
+    engine: row.engine ?? null,
+    engineVersion: row.engine_version ?? null,
+    firstSeenAt: row.first_seen_at,
+    lastSeenAt: row.last_seen_at,
+    resolvedAt: row.resolved_at ?? null,
+    suppressedAt: row.suppressed_at ?? null,
+    mitigatedAt: row.mitigated_at ?? null,
+    occurrenceCount: row.occurrence_count
+  };
+}
+function orderedFindings(rows) {
+  return rows.map(readFinding).sort((a, b) => STATE_ORDER[a.state] - STATE_ORDER[b.state] || b.lastSeenAt - a.lastSeenAt || a.fingerprint.localeCompare(b.fingerprint));
+}
+async function startAnalysisRun(input) {
+  const raw = await BrainDatabase.getRawInstance(input.projectId);
+  ensureHistorySchema(raw);
+  const timestamp = now();
+  const id = randomUUID();
+  raw.prepare(`INSERT INTO brain_analysis_run (id,project_id,kind,status,engine_version,input_hash,started_at,finding_count,time_created,time_updated) VALUES (?,?,?,?,?,?,?,?,?,?)`).run(id, input.projectId, input.kind, "running", input.engineVersion ?? ENGINE_VERSION, hash(input.input ?? {}), timestamp, 0, timestamp, timestamp);
+  return readRun(raw.prepare("SELECT * FROM brain_analysis_run WHERE id=?").get(id));
+}
+async function completeAnalysisRun(projectId, runId, findings, options = {}) {
+  const raw = await BrainDatabase.getRawInstance(projectId);
+  ensureHistorySchema(raw);
+  const timestamp = now();
+  const report = { run: {}, findings: [], newFindings: 0, repeatedFindings: 0, resolvedFindings: 0, reopenedFindings: 0, staleFindings: 0, orderedFindings: [] };
+  const finish = raw.transaction(() => {
+    const run = raw.prepare("SELECT * FROM brain_analysis_run WHERE id=? AND project_id=?").get(runId, projectId);
+    if (!run) throw new Error(`analysis run not found: ${runId}`);
+    if (run.status !== "running") throw new Error(`analysis run is not running: ${runId} (status=${run.status})`);
+    const runEngineVersion = run.engine_version;
+    const seen = /* @__PURE__ */ new Set();
+    for (const input of findings) {
+      const fingerprint = fingerprintFinding(run.kind, input);
+      if (seen.has(fingerprint)) continue;
+      seen.add(fingerprint);
+      const evidenceClass = input.evidenceClass ?? null;
+      const engine = input.engine ?? null;
+      const engineVersion = input.engineVersion ?? runEngineVersion;
+      const limitations = input.limitations ?? [];
+      const existing = raw.prepare("SELECT * FROM brain_analysis_finding WHERE project_id=? AND kind=? AND fingerprint=?").get(projectId, run.kind, fingerprint);
+      const priorState = existing ? stateOf(existing.state) : null;
+      const nextState = input.state ? stateOf(input.state) : priorState === "resolved" || priorState === "stale" ? "reopened" : priorState === "suppressed" || priorState === "mitigated" ? priorState : "open";
+      let findingId;
+      if (!existing) {
+        findingId = randomUUID();
+        raw.prepare(`INSERT INTO brain_analysis_finding (id,project_id,kind,fingerprint,rule,title,severity,state,confidence,evidence,location,limitations,evidence_class,engine,engine_version,first_seen_at,last_seen_at,occurrence_count,time_created,time_updated) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(findingId, projectId, run.kind, fingerprint, input.rule, input.title, input.severity, nextState, input.confidence ?? null, json(input.evidence), input.location ?? null, json(limitations), evidenceClass, engine, engineVersion, timestamp, timestamp, 1, timestamp, timestamp);
+        report.newFindings++;
+      } else {
+        findingId = existing.id;
+        raw.prepare(`UPDATE brain_analysis_finding SET state=?, rule=?, title=?, severity=?, confidence=?, evidence=?, location=?, limitations=?, evidence_class=?, engine=?, engine_version=?, last_seen_at=?, occurrence_count=occurrence_count+1, resolved_at=?, suppressed_at=?, mitigated_at=?, time_updated=? WHERE id=?`).run(nextState, input.rule ?? existing.rule, input.title ?? existing.title, input.severity ?? existing.severity, input.confidence ?? existing.confidence ?? null, json(input.evidence), input.location ?? existing.location ?? null, json(input.limitations ?? (existing.limitations ? parseJsonStringArray(existing.limitations) : [])), evidenceClass ?? existing.evidence_class ?? null, engine ?? existing.engine ?? null, engineVersion ?? existing.engine_version ?? null, timestamp, nextState === "resolved" ? timestamp : existing.resolved_at, nextState === "suppressed" ? timestamp : existing.suppressed_at, nextState === "mitigated" ? timestamp : existing.mitigated_at, timestamp, findingId);
+        if (nextState === "reopened") report.reopenedFindings++;
+        else report.repeatedFindings++;
+      }
+      raw.prepare("INSERT INTO brain_analysis_occurrence (id,finding_id,run_id,state,location,evidence,limitations,evidence_class,engine,engine_version,observed_at,time_created,time_updated) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)").run(randomUUID(), findingId, runId, nextState, input.location ?? null, json(input.evidence), json(limitations), evidenceClass, engine, engineVersion, timestamp, timestamp, timestamp);
+    }
+    const prior = options.incremental ? (options.touchedFingerprints ?? []).length > 0 ? raw.prepare("SELECT * FROM brain_analysis_finding WHERE project_id=? AND kind=? AND state IN ('open','reopened') AND fingerprint IN (" + options.touchedFingerprints.map(() => "?").join(",") + ")").all(projectId, run.kind, ...options.touchedFingerprints) : [] : raw.prepare("SELECT * FROM brain_analysis_finding WHERE project_id=? AND kind=? AND state IN ('open','reopened') AND last_seen_at < ?").all(projectId, run.kind, timestamp);
+    for (const row of prior) {
+      if (!seen.has(row.fingerprint)) {
+        raw.prepare("UPDATE brain_analysis_finding SET state='resolved', resolved_at=?, time_updated=? WHERE id=?").run(timestamp, timestamp, row.id);
+        report.resolvedFindings++;
+      }
+    }
+    const retentionMs = (options.retentionDays ?? 90) * 864e5;
+    raw.prepare("DELETE FROM brain_analysis_occurrence WHERE observed_at < ?").run(timestamp - retentionMs);
+    raw.prepare("UPDATE brain_analysis_run SET status='completed', completed_at=?, finding_count=?, time_updated=? WHERE id=?").run(timestamp, seen.size, timestamp, runId);
+    report.run = readRun(raw.prepare("SELECT * FROM brain_analysis_run WHERE id=?").get(runId));
+    const allRows = raw.prepare("SELECT * FROM brain_analysis_finding WHERE project_id=? AND kind=?").all(projectId, run.kind);
+    report.findings = orderedFindings(allRows);
+    report.orderedFindings = report.findings;
+  });
+  finish();
+  return report;
+}
+async function failAnalysisRun(projectId, runId, error) {
+  const raw = await BrainDatabase.getRawInstance(projectId);
+  ensureHistorySchema(raw);
+  const message = error instanceof Error ? error.message : String(error);
+  const timestamp = now();
+  raw.prepare("UPDATE brain_analysis_run SET status='failed', completed_at=?, error=?, time_updated=? WHERE id=? AND project_id=?").run(timestamp, message, timestamp, runId, projectId);
+  return readRun(raw.prepare("SELECT * FROM brain_analysis_run WHERE id=?").get(runId));
+}
+async function getAnalysisHistory(projectId, kind, limit = 20) {
+  const raw = await BrainDatabase.getRawInstance(projectId, { readonly: true });
+  try {
+    return readHistory(raw, projectId, kind, limit);
+  } catch {
+    return { runs: [], findings: [], summary: Object.fromEntries(STATES.map((state) => [state, 0])) };
+  }
+}
+function readHistory(raw, projectId, kind, limit) {
+  const runs = kind ? raw.prepare("SELECT * FROM brain_analysis_run WHERE project_id=? AND kind=? ORDER BY started_at DESC LIMIT ?").all(projectId, kind, limit) : raw.prepare("SELECT * FROM brain_analysis_run WHERE project_id=? ORDER BY started_at DESC LIMIT ?").all(projectId, limit);
+  const findingRows = kind ? raw.prepare("SELECT * FROM brain_analysis_finding WHERE project_id=? AND kind=?").all(projectId, kind) : raw.prepare("SELECT * FROM brain_analysis_finding WHERE project_id=?").all(projectId);
+  const findings = orderedFindings(findingRows);
+  const summary = Object.fromEntries(STATES.map((state) => [state, findings.filter((row) => row.state === state).length]));
+  return { runs: runs.map(readRun), findings, summary };
+}
+async function executeAnalysis(args) {
+  const run = await startAnalysisRun({ projectId: args.projectId, kind: args.kind, input: args.input, engineVersion: args.engineVersion, retentionDays: args.retentionDays });
+  try {
+    const inputs = await args.persist(run);
+    const report = await completeAnalysisRun(args.projectId, run.id, inputs, { retentionDays: args.retentionDays, incremental: args.incremental, touchedFingerprints: args.touchedFingerprints });
+    return { run: report.run, report, findings: report.findings };
+  } catch (error) {
+    await failAnalysisRun(args.projectId, run.id, error);
+    throw error;
+  }
+}
+
+// src/intelligence/health/health-provider.ts
+function parseArray(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string") return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function kindsWithNoEmbeddings(raw, projectId) {
+  try {
+    const rows = raw.prepare(
+      "SELECT s.symbol_type AS kind, COUNT(*) AS c FROM brain_symbol s WHERE s.project_id = ? AND NOT EXISTS (SELECT 1 FROM brain_semantic_embedding e WHERE e.entity_id = s.id) GROUP BY s.symbol_type ORDER BY c DESC"
+    ).all(projectId);
+    return rows.map((row) => ({ kind: String(row.kind), count: Number(row.c) }));
+  } catch {
+    return [];
+  }
+}
+var refreshQueues = /* @__PURE__ */ new Map();
+var detachedRefreshes = /* @__PURE__ */ new Map();
+function queueRefresh(projectId, projectPath, force, logger) {
+  const previous = refreshQueues.get(projectId) ?? Promise.resolve();
+  const current = previous.catch(() => void 0).then(async () => {
+    const database = await BrainDatabase.getRawInstance(projectId);
+    if (force) wipeProjectData(database);
+    return indexProjectParallel(projectId, projectPath, {
+      isIncremental: !force,
+      ...logger ? { logger } : {}
+    });
+  });
+  refreshQueues.set(projectId, current);
+  void current.finally(() => {
+    if (refreshQueues.get(projectId) === current) refreshQueues.delete(projectId);
+  }).catch(() => void 0);
+  return current;
+}
+function emptyIndexReport(projectId, projectPath, options, warnings, timing, startedCall, refresh, error) {
+  const reason = error instanceof Error ? error.message : String(error);
+  warnings.push({
+    code: "EMPTY_INDEX",
+    message: `no usable index for ${projectPath}: ${reason}. This is an unindexed project, not a verified healthy one. Run bb_health with refresh=true, wait=true (or: bb index "${projectPath}") to build it.`,
+    severity: "error"
+  });
+  let pathChecks = null;
+  let scope = null;
+  if (options.paths && options.paths.length > 0) {
+    const resolved = [];
+    const refused = [];
+    for (const requested of options.paths) {
+      const trimmed = String(requested).trim();
+      const abs = resolve(projectPath, trimmed);
+      const rel = relativePath(projectPath, abs);
+      if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        refused.push({ requested: trimmed, reason: `path escapes project root: ${trimmed}` });
+        continue;
+      }
+      let onDisk = false;
+      try {
+        onDisk = statSync(abs).isFile();
+      } catch {
+        onDisk = false;
+      }
+      resolved.push({
+        requested: trimmed,
+        path: rel.split(sep).join("/"),
+        status: onDisk ? "not-indexed" : "absent",
+        reason: onDisk ? "on disk but the project has no index \u2014 run refresh=true (or bb index) to index it" : "not in the index and not on disk \u2014 this path does not exist",
+        language: null,
+        symbols: 0,
+        verifiedBy: null
+      });
+    }
+    pathChecks = resolved;
+    scope = {
+      kind: "paths",
+      requested: options.paths.map((p) => String(p).trim()),
+      refused,
+      note: "no index exists, so no freshness can be verified. Every other line in this report is a zero over an empty index, not a project measurement."
+    };
+    const notIndexed = resolved.filter((r) => r.status === "not-indexed").map((r) => r.path);
+    if (notIndexed.length > 0) {
+      warnings.push({ code: "PATHS_NOT_INDEXED", message: `${notIndexed.length} of the ${resolved.length} path(s) you named exist on disk but the project has no index: ${notIndexed.slice(0, 5).join(", ")}. Index the project (refresh=true) before asking for per-file freshness.`, severity: "warning" });
+    }
+    if (refused.length > 0) {
+      warnings.push({ code: "PATHS_REFUSED", message: `${refused.length} path(s) were REFUSED and are NOT checked: ${refused.map((r) => `${r.requested} (${r.reason})`).join("; ")}. A refused path is not a clean one.`, severity: "error" });
+    }
+  }
+  timing.totalMs = Date.now() - startedCall;
+  const zeroReasons = { "metadata-fast-path": 0, "hash-match": 0, "hash-differs": 0, "file-gone": 0, unreadable: 0, "no-row": 0 };
+  return {
+    projectId,
+    projectPath,
+    timestamp: Date.now(),
+    counts: { files: 0, symbols: 0, relationships: 0, imports: 0, syntaxErrors: 0 },
+    indexStatus: { lastFullIndex: null, lastIncrementalIndex: null, indexedFiles: null, totalFilesDiscovered: null, indexShortfall: 0, isIncomplete: false, indexingVersion: null, status: null, errors: [], recordPresent: false },
+    performanceStats: { schemaVersion: null, runs: [], latestRun: null },
+    freshness: {
+      mode: "complete",
+      requestedMode: options.freshness ?? "sampled",
+      checked: 0,
+      total: 0,
+      fresh: 0,
+      stale: 0,
+      missing: 0,
+      staleFiles: [],
+      missingFiles: [],
+      unresolved: 0,
+      isComplete: true,
+      reasons: { byKind: zeroReasons, freshVerifiedByContent: 0, freshVerifiedByMetadata: 0, isSample: false }
+    },
+    embeddings: { total: 0, embeddedEntities: 0, symbolCoveragePercent: 0, models: [], embeddedByEntityType: [], unembeddedKinds: [], byLanguage: [] },
+    schema: { version: null, migration: null, tables: 0 },
+    runtime: { runtime: typeof Bun !== "undefined" ? "bun" : "node", version: process.version, database: "sqlite" },
+    timing,
+    integrity: null,
+    scope,
+    pathChecks,
+    unindexed: null,
+    analysisRuns: null,
+    refresh,
+    effectiveConfig: null,
+    embeddingChain: null,
+    languages: [],
+    verbose: options.verbose === true,
+    warnings
+  };
+}
+async function getUnifiedHealth(projectId, projectPath, options = {}) {
+  const timing = { totalMs: 0, aggregatesMs: 0, freshnessMs: 0, integrityMs: 0, refreshMs: 0, pathsMs: 0, unindexedMs: 0 };
+  const startedCall = Date.now();
+  const now2 = () => Date.now();
+  const warnings = [];
+  const refresh = { requested: options.refresh === true || options.force === true, force: options.force === true, wait: options.wait !== false, completed: false, durationMs: null, processedFiles: null, derived: null };
+  const priorDetached = detachedRefreshes.get(projectId);
+  if (priorDetached) {
+    if (priorDetached.state === "running") {
+      warnings.push({ code: "REFRESH_IN_PROGRESS", message: `a detached refresh started ${Math.round((Date.now() - priorDetached.startedAt) / 1e3)}s ago is still running${priorDetached.force ? " AFTER A FORCE WIPE \u2014 the index is mid-rebuild and every count below is transient" : ""}`, severity: "warning" });
+    } else if (priorDetached.state === "failed") {
+      warnings.push({ code: "REFRESH_FAILED_ASYNC", message: `the detached refresh started ${Math.round((Date.now() - priorDetached.startedAt) / 1e3)}s ago FAILED${priorDetached.force ? " after a force wipe, so the index may be empty" : ""}: ${priorDetached.error ?? "unknown error"}. Re-run with refresh=true, wait=true.`, severity: "error" });
+      detachedRefreshes.delete(projectId);
+    } else {
+      warnings.push({ code: "REFRESH_COMPLETED", message: `the detached refresh started ${Math.round((Date.now() - priorDetached.startedAt) / 1e3)}s ago completed in ${priorDetached.durationMs ?? "?"}ms (${priorDetached.processedFiles ?? "?"} file(s) processed, derived=${priorDetached.derived ?? "unknown"}). This notice is one-shot.`, severity: "warning" });
+      detachedRefreshes.delete(projectId);
+    }
+  }
+  const writeRequested = options.refresh === true || options.force === true;
+  let raw;
+  try {
+    raw = await BrainDatabase.getRawInstance(projectId, { readonly: !writeRequested });
+  } catch (error) {
+    if (writeRequested) {
+      warnings.push({ code: "REFRESH_FAILED", message: `the refresh could not open the index: ${error instanceof Error ? error.message : String(error)}. Nothing was reindexed.`, severity: "error" });
+    }
+    return emptyIndexReport(projectId, projectPath, options, warnings, timing, startedCall, refresh, error);
+  }
+  if (options.refresh === true || options.force === true) {
+    const started = Date.now();
+    const refreshPromise = queueRefresh(projectId, projectPath, options.force === true, options.logger);
+    if (options.wait === false) {
+      refresh.wait = false;
+      const record = { startedAt: started, force: options.force === true, state: "running" };
+      detachedRefreshes.set(projectId, record);
+      warnings.push({
+        code: "REFRESH_STARTED",
+        message: `refresh started in the background; returning the current snapshot${record.force ? ". force=true WIPES the index before rebuilding, so these counts are transient and the next call will report whether it finished" : ""}`,
+        severity: "warning"
+      });
+      void refreshPromise.then(
+        (stats) => {
+          if (detachedRefreshes.get(projectId) !== record) return;
+          record.durationMs = Date.now() - started;
+          record.processedFiles = stats?.processedFiles ?? stats?.totalFiles ?? 0;
+          record.derived = typeof stats?.summary?.derivedPass === "string" ? stats.summary.derivedPass : "unknown";
+          if (record.force && record.processedFiles === 0) {
+            record.state = "failed";
+            record.error = "the forced rebuild completed but indexed 0 files \u2014 force=true wiped the index and the rebuild put nothing back, so the index is now empty";
+          } else {
+            record.state = "completed";
+          }
+        },
+        (error) => {
+          if (detachedRefreshes.get(projectId) !== record) return;
+          record.state = "failed";
+          record.durationMs = Date.now() - started;
+          record.error = error instanceof Error ? error.message : String(error);
+        }
+      );
+    } else {
+      try {
+        const stats = await refreshPromise;
+        refresh.completed = true;
+        refresh.durationMs = Date.now() - started;
+        timing.refreshMs = refresh.durationMs;
+        refresh.processedFiles = stats.processedFiles ?? stats.totalFiles ?? 0;
+        refresh.derived = typeof stats?.summary?.derivedPass === "string" ? stats.summary.derivedPass : "unknown";
+        try {
+          raw = await BrainDatabase.getRawInstance(projectId, { readonly: true });
+        } catch {
+          raw = await BrainDatabase.getRawInstance(projectId);
+        }
+      } catch (error) {
+        warnings.push({ code: "REFRESH_FAILED", message: error instanceof Error ? error.message : String(error), severity: "error" });
+        refresh.durationMs = Date.now() - started;
+      }
+    }
+  }
+  const count = (table) => raw.prepare(`SELECT COUNT(*) c FROM ${table} WHERE project_id=?`).get(projectId)?.c ?? 0;
+  const files = count("brain_file"), symbols = count("brain_symbol"), relationships = count("brain_relationship"), imports = count("brain_import");
+  const syntaxErrorRows = raw.prepare("SELECT relative_path FROM brain_file WHERE project_id=? AND COALESCE(has_syntax_errors,0)=1 ORDER BY relative_path LIMIT 8").all(projectId);
+  const syntaxErrors = raw.prepare("SELECT COUNT(*) c FROM brain_file WHERE project_id=? AND COALESCE(has_syntax_errors,0)=1").get(projectId)?.c ?? 0;
+  const status = raw.prepare("SELECT * FROM brain_index_status WHERE project_id=?").get(projectId);
+  const freshnessMode = options.freshness ?? "sampled";
+  const sampleSize = options.sampleSize ?? 200;
+  const freshnessStarted = now2();
+  const allFileRows = raw.prepare("SELECT id, relative_path FROM brain_file WHERE project_id=?").all(projectId);
+  const fileRows = freshnessMode === "complete" ? selectSampleFiles(allFileRows, Number.MAX_SAFE_INTEGER) : selectSampleFiles(allFileRows, sampleSize);
+  const resolved = resolveRowsFreshnessDetailed(raw, projectId, fileRows.map((row) => ({ fileId: row.id })), { freshnessMode });
+  timing.freshnessMs = now2() - freshnessStarted;
+  const statuses = resolved.statuses;
+  let fresh = 0, stale = 0, missing = 0;
+  const staleFiles = [], missingFiles = [];
+  const reasonCounts = {
+    "metadata-fast-path": 0,
+    "hash-match": 0,
+    "hash-differs": 0,
+    "file-gone": 0,
+    unreadable: 0,
+    "no-row": 0
+  };
+  for (const row of fileRows) {
+    const value = statuses.get(row.id);
+    const why = resolved.reasons.get(row.id);
+    if (why) reasonCounts[why]++;
+    if (value === "fresh") fresh++;
+    else if (value === "missing") {
+      missing++;
+      missingFiles.push(row.relative_path);
+    } else if (value === "stale") {
+      stale++;
+      staleFiles.push(row.relative_path);
+    }
+  }
+  const unresolved = fileRows.length - (fresh + stale + missing);
+  const reasonTotal = Object.values(reasonCounts).reduce((a, b) => a + b, 0) + unresolved;
+  const aggregatesStarted = now2();
+  const fileLangRows = raw.prepare(
+    "SELECT language, COUNT(DISTINCT id) AS files FROM brain_file WHERE project_id = ? GROUP BY language"
+  ).all(projectId);
+  let languageRows = [];
+  if (options.verbose === true) {
+    const symLangRows = raw.prepare(
+      "SELECT f.language AS language, COUNT(*) AS symbols FROM brain_symbol s JOIN brain_file f ON f.id = s.file_id AND f.project_id = ? WHERE s.project_id = ? GROUP BY f.language"
+    ).all(projectId, projectId);
+    const langMap = /* @__PURE__ */ new Map();
+    for (const fr of fileLangRows) langMap.set(String(fr.language), { language: fr.language, files: Number(fr.files), symbols: 0 });
+    for (const sr of symLangRows) {
+      const bucket = langMap.get(String(sr.language));
+      if (bucket) bucket.symbols = Number(sr.symbols);
+    }
+    languageRows = [...langMap.values()].sort((a, b) => {
+      if (b.files !== a.files) return b.files - a.files;
+      if (a.language === b.language) return 0;
+      if (a.language == null) return -1;
+      if (b.language == null) return 1;
+      return String(a.language) < String(b.language) ? -1 : 1;
+    });
+  }
+  const modelRows = raw.prepare("SELECT embedding_model AS model, COUNT(*) c, GROUP_CONCAT(DISTINCT vector_dimension) dims FROM brain_semantic_embedding WHERE project_id=? GROUP BY embedding_model ORDER BY c DESC").all(projectId);
+  const entityTypeRows = options.verbose === true ? raw.prepare("SELECT entity_type, COUNT(*) c FROM brain_semantic_embedding WHERE project_id=? GROUP BY entity_type ORDER BY c DESC").all(projectId) : [];
+  const embeddingTotal = modelRows.reduce((sum, row) => sum + Number(row.c ?? 0), 0);
+  const embeddedEntities = raw.prepare("SELECT COUNT(DISTINCT entity_id) c FROM brain_semantic_embedding WHERE project_id=?").get(projectId)?.c ?? 0;
+  const schema = raw.prepare("SELECT version, migration_name FROM brain_schema_version ORDER BY version DESC LIMIT 1").get();
+  const tableCount = raw.prepare("SELECT COUNT(*) c FROM sqlite_master WHERE type='table' AND name LIKE 'brain_%'").get()?.c ?? 0;
+  let effectiveConfig = null;
+  let embeddingChain = null;
+  if (options.verbose === true) {
+    try {
+      embeddingChain = buildEmbeddingDiagnosis({ state: describeEmbeddingConfig() });
+    } catch {
+      embeddingChain = null;
+    }
+    try {
+      const { resolveEmbeddingConfig } = await import("./config-HZAAYDP3.js");
+      const fileCfg = await Config.get();
+      const effFull = resolveEmbeddingConfig(fileCfg);
+      effectiveConfig = { baseURL: effFull.baseURL, model: effFull.model, configured: effFull.configured, sources: effFull.sources };
+    } catch {
+      effectiveConfig = null;
+    }
+  }
+  const embeddedByLanguage = (() => {
+    if (options.verbose !== true) return [];
+    try {
+      const rows = raw.prepare(
+        "SELECT f.language AS language, COUNT(DISTINCT s.id) AS embedded FROM brain_symbol s JOIN brain_file f ON f.id = s.file_id AND f.project_id = ? WHERE s.project_id = ? AND EXISTS (SELECT 1 FROM brain_semantic_embedding e WHERE e.entity_id = s.id) GROUP BY f.language"
+      ).all(projectId, projectId);
+      const have = new Map(rows.map((r) => [String(r.language), Number(r.embedded)]));
+      return languageRows.map((l) => ({
+        language: l.language,
+        symbols: l.symbols,
+        embedded: have.get(String(l.language)) ?? 0,
+        searchablePercent: l.symbols > 0 ? Math.round((have.get(String(l.language)) ?? 0) / l.symbols * 1e3) / 10 : 0
+      }));
+    } catch {
+      return [];
+    }
+  })();
+  timing.aggregatesMs = now2() - aggregatesStarted;
+  let unindexed = null;
+  const unindexedStarted = now2();
+  if (options.checkUnindexed === true) {
+    const walkStarted = now2();
+    try {
+      const rootStat = statSync(projectPath);
+      if (!rootStat.isDirectory()) throw new Error(`project path is not a directory: ${projectPath}`);
+      const { discoverIndexableFiles } = await import("./parallel-indexer-4PW3AFXP.js");
+      const onDisk = await discoverIndexableFiles(projectPath);
+      const indexed = new Set(
+        raw.prepare("SELECT path FROM brain_file WHERE project_id=?").all(projectId).map((r) => String(r.path))
+      );
+      const missingFromIndex = onDisk.filter((p) => !indexed.has(p)).map((p) => relativePath(projectPath, p)).sort();
+      unindexed = {
+        eligibleOnDisk: onDisk.length,
+        indexed: indexed.size,
+        unindexedCount: missingFromIndex.length,
+        unindexedFiles: missingFromIndex,
+        walkMs: now2() - walkStarted,
+        population: "files this project would index under the indexer's own rules (.gitignore, .bbignore, skip directories, the compiled-mode path filter, extension and shell-shebang gates, and the >5MB size skip). A file excluded by those rules is correctly absent from this count and is NOT a gap in the index."
+      };
+      if (missingFromIndex.length > 0) {
+        warnings.push({
+          code: "UNINDEXED_FILES",
+          message: `${missingFromIndex.length} file(s) on disk are not in the index: ${missingFromIndex.slice(0, 5).join(", ")}${missingFromIndex.length > 5 ? `, +${missingFromIndex.length - 5} more` : ""}. The indexer would index these, so it has not run since they appeared. Run refresh=true, or bb_index on the specific paths.`,
+          severity: "warning"
+        });
+      }
+    } catch (error) {
+      warnings.push({ code: "UNINDEXED_SCAN_FAILED", message: `could not compare the index against disk: ${error instanceof Error ? error.message : String(error)}. Whether the index is COMPLETE is UNKNOWN \u2014 this is not a verified result.`, severity: "warning" });
+      unindexed = null;
+    }
+    timing.unindexedMs = now2() - unindexedStarted;
+  }
+  let pathChecks = null;
+  let scope = null;
+  if (options.paths && options.paths.length > 0) {
+    const scopeStarted = now2();
+    const { resolveSafeEditPath } = await import("./edit-engine-KM7MPFEC.js");
+    const resolved2 = [];
+    const refused = [];
+    const wanted = [];
+    for (const requested of options.paths) {
+      const trimmed = String(requested).trim();
+      const key = resolve(projectPath, trimmed);
+      const asRelative = relativePath(projectPath, key);
+      if (asRelative === "" || asRelative === ".." || asRelative.startsWith(`..${sep}`) || isAbsolute(asRelative)) {
+        refused.push({ requested: trimmed, reason: `path escapes project root: ${trimmed}` });
+        continue;
+      }
+      let abs;
+      try {
+        abs = resolveSafeEditPath(projectPath, asRelative);
+      } catch (e) {
+        refused.push({ requested: trimmed, reason: e instanceof Error ? e.message : String(e) });
+        continue;
+      }
+      const row = raw.prepare("SELECT id, language FROM brain_file WHERE project_id=? AND path=?").get(projectId, key);
+      wanted.push({ requested: trimmed, abs: key, realAbs: abs, rel: asRelative, fileId: row ? String(row.id) : null, row });
+    }
+    const ids = wanted.map((w) => w.fileId).filter((x) => !!x);
+    const scoped = ids.length ? resolveRowsFreshnessDetailed(raw, projectId, ids.map((id) => ({ fileId: id })), { freshnessMode: "complete" }) : null;
+    for (const w of wanted) {
+      if (!w.fileId || !w.row) {
+        let onDisk = false;
+        try {
+          onDisk = statSync(w.abs).isFile();
+        } catch {
+          onDisk = false;
+        }
+        resolved2.push({
+          requested: w.requested,
+          path: w.rel,
+          status: onDisk ? "not-indexed" : "absent",
+          reason: onDisk ? "on disk but not in the index \u2014 the indexer would index this, so it has not run since the file appeared" : "not in the index and not on disk \u2014 this path does not exist",
+          language: null,
+          symbols: 0,
+          verifiedBy: null
+        });
+        continue;
+      }
+      const status2 = scoped.statuses.get(w.fileId);
+      const reason = scoped.reasons.get(w.fileId) ?? null;
+      const symbolCount = raw.prepare("SELECT COUNT(*) c FROM brain_symbol WHERE project_id=? AND file_id=?").get(projectId, w.fileId)?.c ?? 0;
+      resolved2.push({
+        requested: w.requested,
+        path: w.rel,
+        // The resolver's `missing` covers BOTH "deleted" and "unreadable"; for a
+        // caller asking about ONE file those are different, so the reason is
+        // carried rather than flattened into one word.
+        status: status2 === "missing" ? reason === "file-gone" ? "gone" : "gone" : status2 ?? "absent",
+        reason,
+        language: w.row.language ?? null,
+        symbols: Number(symbolCount),
+        verifiedBy: reason === "metadata-fast-path" ? "mtime+size only (file not read)" : reason === "hash-match" ? "content hash" : null
+      });
+    }
+    pathChecks = resolved2;
+    scope = {
+      kind: "paths",
+      requested: options.paths.map((p) => String(p).trim()),
+      refused,
+      note: "This block answers the paths you named. Every other line in this report \u2014 counts, embeddings, freshness, index \u2014 is PROJECT-WIDE and is NOT scoped to these paths."
+    };
+    const unindexedPaths = resolved2.filter((r) => r.status === "not-indexed").map((r) => r.path);
+    if (unindexedPaths.length > 0) {
+      warnings.push({ code: "PATHS_NOT_INDEXED", message: `${unindexedPaths.length} of the ${resolved2.length} path(s) you named exist on disk but are NOT in the index: ${unindexedPaths.slice(0, 5).join(", ")}. A freshness answer about a file the index has never seen would be meaningless; index them with bb_index on those paths.`, severity: "warning" });
+    }
+    const stalePaths = resolved2.filter((r) => r.status === "stale").map((r) => r.path);
+    if (stalePaths.length > 0) {
+      warnings.push({ code: "PATHS_STALE", message: `${stalePaths.length} of the ${resolved2.length} path(s) you named changed on disk since indexing: ${stalePaths.slice(0, 5).join(", ")}.`, severity: "warning" });
+    }
+    if (refused.length > 0) {
+      warnings.push({ code: "PATHS_REFUSED", message: `${refused.length} path(s) were REFUSED and are NOT checked: ${refused.map((r) => `${r.requested} (${r.reason})`).join("; ")}. A refused path is not a clean one.`, severity: "error" });
+    }
+    timing.pathsMs = now2() - scopeStarted;
+  }
+  let integrity = null;
+  if (options.integrity === true) {
+    const integrityStarted = now2();
+    const coversEveryFile = fileRows.length >= files;
+    try {
+      integrity = await runIndexHealthCheck(projectId, {
+        diskScan: "complete",
+        preResolved: coversEveryFile ? { total: files, reasons: reasonCounts } : null
+      });
+    } catch (error) {
+      warnings.push({ code: "INTEGRITY_FAILED", message: error instanceof Error ? error.message : String(error), severity: "error" });
+    }
+    timing.integrityMs = now2() - integrityStarted;
+  }
+  let analysisRuns = null;
+  if (options.includeAnalysisRuns === true) {
+    try {
+      const history = await getAnalysisHistory(projectId, void 0, 100);
+      const runTotal = raw.prepare("SELECT COUNT(*) c FROM brain_analysis_run WHERE project_id=?").get(projectId)?.c ?? null;
+      analysisRuns = { runs: runTotal ?? history.runs.length, findings: history.findings.length, byState: history.summary, runTotalKnown: runTotal !== null };
+    } catch (error) {
+      warnings.push({ code: "ANALYSIS_HISTORY_FAILED", message: error instanceof Error ? error.message : String(error), severity: "warning" });
+    }
+  }
+  if (syntaxErrors > 0) {
+    const named = syntaxErrorRows.map((r) => r.relative_path);
+    const shown = named.length === syntaxErrors ? named.join(", ") : `${named.join(", ")}${named.length > 0 ? "\u2026" : ""}`;
+    warnings.push({
+      code: "SYNTAX_ERRORS",
+      message: `${syntaxErrors} indexed files have syntax errors${shown ? `: ${shown}` : ""}`,
+      severity: "warning"
+    });
+  }
+  if (unresolved > 0) warnings.push({ code: "UNRESOLVED_FILES", message: `${unresolved} indexed files could not be classified and are counted as neither fresh nor stale`, severity: "warning" });
+  if (stale + missing > 0) {
+    const edited = reasonCounts["hash-differs"];
+    const deleted = reasonCounts["file-gone"];
+    const denied = reasonCounts["unreadable"] + reasonCounts["no-row"];
+    const mix = [edited ? `${edited} changed on disk` : "", deleted ? `${deleted} deleted from disk` : "", denied ? `${denied} unreadable or unindexed` : ""].filter(Boolean).join(", ");
+    const scope2 = fileRows.length >= files ? `of ${files} indexed files` : `in a ${fileRows.length}-file sample of ${files} \u2014 a LOWER BOUND on the project, not a total (freshness="complete" counts them all)`;
+    warnings.push({
+      code: "STALE_FILES",
+      message: `${stale} stale and ${missing} missing ${scope2}${mix ? ` (${mix})` : ""}`,
+      severity: "warning"
+    });
+  }
+  const statusRecordPresent = status != null;
+  if (files === 0) {
+    warnings.push({
+      code: "EMPTY_INDEX",
+      message: "the index holds 0 files and 0 symbols \u2014 this is either an unindexed project or an index whose rebuild did not finish (a forced refresh wipes before it rebuilds). Run refresh=true, wait=true to (re)build it.",
+      severity: "error"
+    });
+  }
+  const recordedTotal = typeof status?.total_files === "number" ? status.total_files : null;
+  const recordedIndexed = typeof status?.indexed_files === "number" ? status.indexed_files : null;
+  const statusCountersDisagree = statusRecordPresent && recordedTotal !== null && files > 0 && recordedTotal < files;
+  const indexShortfall = recordedTotal !== null && recordedIndexed !== null && recordedIndexed < recordedTotal ? { missing: recordedTotal - recordedIndexed, total: recordedTotal, indexed: recordedIndexed } : null;
+  if (indexShortfall) {
+    const contradicted = status?.status === "complete";
+    warnings.push({
+      code: "INCOMPLETE_INDEX",
+      message: `the last index run recorded ${indexShortfall.indexed} of ${indexShortfall.total} files as indexed \u2014 ${indexShortfall.missing} file(s) were found by the walk but never written, so the index is INCOMPLETE${contradicted ? ' even though the status field says "complete"' : ""}. counts below describe a partial index and any answer derived from it covers only what was indexed. Run refresh=true, force=true to rebuild from scratch.`,
+      severity: "error"
+    });
+  }
+  if (statusCountersDisagree) {
+    warnings.push({
+      code: "INDEX_STATUS_COUNTERS",
+      message: `the index status record's last-run counters (${recordedIndexed ?? "?"} indexed of ${recordedTotal ?? "?"} discovered) describe a smaller population than the ${files} files the index actually holds \u2014 these counters are the LAST RUN's numbers, not index-wide totals, and must not be read as either a complete count or a shortfall of this index`,
+      severity: "warning"
+    });
+  }
+  if (!statusRecordPresent) {
+    warnings.push({
+      code: "NO_INDEX_STATUS",
+      message: "no brain_index_status row for this project \u2014 indexedFiles/status/errors/lastFullIndex are UNRECORDED, not zero. counts.files is measured from brain_file. Reindex (refresh=true) to restore the record.",
+      severity: "warning"
+    });
+  }
+  const indexingErrors = parseArray(status?.indexing_errors);
+  if (indexingErrors.length > 0) warnings.push({ code: "INDEXING_ERRORS", message: `${indexingErrors.length} indexing errors recorded`, severity: "warning" });
+  const perfRaw = status?.performance_stats;
+  const performanceStats = typeof perfRaw === "string" && perfRaw ? (() => {
+    try {
+      const p = JSON.parse(perfRaw);
+      return Array.isArray(p?.runs) ? p : null;
+    } catch {
+      return null;
+    }
+  })() : null;
+  const perfRuns = performanceStats?.runs ?? [];
+  const latestPerfRun = perfRuns.length > 0 ? perfRuns[perfRuns.length - 1] : null;
+  timing.totalMs = now2() - startedCall;
+  return {
+    projectId,
+    projectPath,
+    timestamp: Date.now(),
+    counts: { files, symbols, relationships, imports, syntaxErrors },
+    indexStatus: {
+      lastFullIndex: status?.last_full_index ?? null,
+      lastIncrementalIndex: status?.last_incremental_index ?? null,
+      indexedFiles: status?.indexed_files ?? null,
+      // the walk-vs-write shortfall, exposed as data. A consumer can
+      // branch on this without parsing a warning message.
+      totalFilesDiscovered: recordedTotal,
+      indexShortfall: indexShortfall ? indexShortfall.missing : 0,
+      isIncomplete: indexShortfall !== null,
+      indexingVersion: status?.indexing_version ?? null,
+      status: status?.status ?? null,
+      errors: indexingErrors,
+      recordPresent: statusRecordPresent
+    },
+    performanceStats: { schemaVersion: performanceStats?.schemaVersion ?? null, runs: perfRuns, latestRun: latestPerfRun },
+    // `mode` reports what was ACTUALLY checked, not what was asked
+    // for. A caller passing sampleSize >= the file count gets every file, and
+    // saying "sampled" about a complete check is the mirror image of the bug
+    // this replaced. `isComplete` lets a JSON consumer refuse to read an
+    // estimate as a census.
+    freshness: {
+      mode: fileRows.length >= files ? "complete" : "sampled",
+      requestedMode: freshnessMode,
+      checked: fileRows.length,
+      total: files,
+      fresh,
+      stale,
+      missing,
+      staleFiles,
+      missingFiles,
+      unresolved,
+      isComplete: fileRows.length >= files,
+      reasons: {
+        byKind: reasonCounts,
+        freshVerifiedByContent: reasonCounts["hash-match"],
+        freshVerifiedByMetadata: reasonCounts["metadata-fast-path"],
+        isSample: fileRows.length < files
+      }
+    },
+    embeddings: {
+      total: embeddingTotal,
+      embeddedEntities,
+      symbolCoveragePercent: symbols > 0 ? Math.round(embeddedEntities / symbols * 1e3) / 10 : 0,
+      models: modelRows.map((row) => ({ model: row.model, count: Number(row.c), dimensions: String(row.dims ?? "").split(",").filter(Boolean).map(Number) })),
+      // the percentage above is a ratio of two counts, and what it
+      // measures is narrower than the label admits. On this repo: 4,569
+      // function + 2,836 class + 1,838 method + 652 interface = 9,895 embedded
+      // entities against 45,018 symbols = "22%". All 9,895 are real
+      // brain_symbol rows (0 orphans), so the arithmetic is sound — but 22% is
+      // the share of the corpus made of the four kinds the embedder supports,
+      // not the share of the corpus that is semantically searchable. The other
+      // kinds are not partially covered; they are not attempted at all, and
+      // that is a fact the reader could not see.
+      embeddedByEntityType: entityTypeRows.map((row) => ({ entityType: String(row.entity_type), count: Number(row.c) })),
+      unembeddedKinds: kindsWithNoEmbeddings(raw, projectId),
+      // the join. `searchablePercent` is the share of that language's
+      // symbols a semantic query can reach at all; a language at 0% is invisible
+      // to bb_ask no matter how healthy the project looks overall.
+      byLanguage: embeddedByLanguage
+    },
+    schema: { version: schema?.version ?? null, migration: schema?.migration_name ?? null, tables: tableCount },
+    // `parserStatus` was typed `"available" | "unknown"`, hardcoded to
+    // "unknown", and read by no code path in any mode. A field that cannot
+    // vary and is never printed is not a measurement; it is a claim in a type.
+    runtime: { runtime: typeof Bun !== "undefined" ? "bun" : "node", version: process.version, database: raw.driver ?? "sqlite" },
+    timing,
+    unindexed,
+    scope,
+    pathChecks,
+    integrity,
+    analysisRuns,
+    refresh,
+    effectiveConfig,
+    embeddingChain,
+    languages: languageRows,
+    verbose: options.verbose === true,
+    warnings
+  };
+}
+function renderFileList(label, files, cap = 20) {
+  if (files.length === 0) return `${label}: none`;
+  if (files.length <= cap) return `${label}: ${files.join(", ")}`;
+  return `${label}: ${files.length} total, first ${cap}: ${files.slice(0, cap).join(", ")} \u2014 use freshness="complete" and read freshness.staleFiles in the JSON for the rest`;
+}
+function renderTiming(t) {
+  const parts = [];
+  if (t.refreshMs) parts.push(`refresh=${t.refreshMs}ms`);
+  if (t.integrityMs) parts.push(`integrity=${t.integrityMs}ms`);
+  if (t.unindexedMs) parts.push(`unindexed-walk=${t.unindexedMs}ms`);
+  if (t.freshnessMs) parts.push(`freshness=${t.freshnessMs}ms`);
+  if (t.aggregatesMs) parts.push(`aggregates=${t.aggregatesMs}ms`);
+  return `total=${t.totalMs}ms${parts.length ? ` (${parts.join(" ")})` : ""}`;
+}
+function firstSentence(text) {
+  const trimmed = text.trim();
+  let cut = trimmed.length;
+  for (let i = 0; i < trimmed.length; i++) {
+    const ch = trimmed[i];
+    if (ch !== "." && ch !== "!" && ch !== "?") continue;
+    const next = trimmed[i + 1];
+    if (next === void 0 || next === " " || next === "	" || next === "\n" || next === "\r") {
+      cut = i + 1;
+      break;
+    }
+  }
+  let out = "";
+  let inSpace = false;
+  for (let i = 0; i < cut; i++) {
+    const ch = trimmed[i];
+    const space = ch === " " || ch === "	" || ch === "\n" || ch === "\r";
+    if (space) {
+      if (!inSpace) out += " ";
+      inSpace = true;
+    } else {
+      out += ch;
+      inSpace = false;
+    }
+  }
+  return out.length > 400 ? `${out.slice(0, 397)}\u2026` : out;
+}
+function renderReasonMix(f) {
+  const r = f.reasons.byKind;
+  const parts = [];
+  if (r["hash-match"]) parts.push(`${r["hash-match"]} fresh by content hash`);
+  if (r["metadata-fast-path"]) parts.push(`${r["metadata-fast-path"]} fresh by mtime+size only (file not read \u2014 a same-size edit preserving the mtime reads as fresh)`);
+  if (r["hash-differs"]) parts.push(`${r["hash-differs"]} stale: content changed (reindex these)`);
+  if (r["file-gone"]) parts.push(`${r["file-gone"]} missing: deleted from disk (a refresh prunes them)`);
+  if (r.unreadable) parts.push(`${r.unreadable} missing: unreadable (permissions or a non-file \u2014 these will fail every read)`);
+  if (r["no-row"]) parts.push(`${r["no-row"]} missing: no index row for the id`);
+  if (f.unresolved) parts.push(`${f.unresolved} unclassified`);
+  if (!parts.length) return "nothing checked";
+  return `${parts.join("; ")}${f.reasons.isSample ? ` \u2014 over the ${f.checked}-file SAMPLE, not the project` : ""}`;
+}
+function formatUnifiedHealth(report) {
+  const c = report.counts, f = report.freshness, e = report.embeddings;
+  const lastRunCountersOnly = report.indexStatus.totalFilesDiscovered !== null && report.indexStatus.totalFilesDiscovered < report.counts.files;
+  const pre = [];
+  if (report.scope && report.pathChecks) {
+    pre.push(`SCOPED ANSWER for ${report.pathChecks.length} path(s) you named \u2014 everything below this block is PROJECT-WIDE:`);
+    for (const p of report.pathChecks) {
+      const bare = p.status === "gone" || p.status === "not-indexed" || p.status === "absent";
+      const detail = [bare ? null : `${p.symbols} symbol(s)`, p.language, p.verifiedBy ? `verified by ${p.verifiedBy}` : null].filter(Boolean).join(", ");
+      const stateWord = p.status === "gone" && p.reason === "unreadable" ? "gone?" : p.status;
+      const goneNote = p.status === "gone" && p.reason === "unreadable" ? " (exists but could not be read \u2014 not deleted)" : "";
+      pre.push(`  ${stateWord.padEnd(12)} ${p.path}${detail ? ` \u2014 ${detail}` : ""}${bare ? ` \u2014 ${p.reason}${goneNote}` : ""}`);
+    }
+    if (report.scope.refused.length) pre.push(`  REFUSED (not checked): ${report.scope.refused.map((r) => `${r.requested} \u2014 ${r.reason}`).join("; ")}`);
+    pre.push("");
+  }
+  const staleIsEstimate = !f.isComplete;
+  const staleShown = staleIsEstimate ? `${f.stale} of ${f.checked} sampled stale (~${Math.round(f.stale / Math.max(1, f.checked) * f.total)} of ${f.total} estimated)` : `${f.stale} of ${f.total} stale`;
+  const lines = [
+    `project: ${report.projectPath}`,
+    `projectId: ${report.projectId}`,
+    `files=${c.files} symbols=${c.symbols} relationships=${c.relationships} imports=${c.imports} syntaxErrors=${c.syntaxErrors}`,
+    `freshness: ${f.fresh} fresh / ${staleShown} / ${f.missing} missing (${f.checked}/${f.total} checked, ${f.mode}${f.mode === "sampled" ? " \u2014 SAMPLE, not a census" : ""})`,
+    // .R: the breakdown is in the DEFAULT output, not verbose, because the
+    // defect is that "215 stale" is not actionable. "stale" is three conditions
+    // with three different fixes, and a caller who has to opt in to learn which
+    // one they have will not learn it.
+    //
+    // The two fresh kinds are named apart because they are different claims:
+    // `hash-match` read the bytes, `metadata-fast-path` accepted an mtime+size
+    // match and never opened the file. Collapsing them into "fresh" hides the
+    // error bound of the whole verdict.
+    `freshness why: ${renderReasonMix(f)}`,
+    // the percentage is a ratio of two counts, so the two counts and
+    // what they divide are all named. "22% symbol coverage" alone reads as
+    // "22% of my code is semantically searchable"; 9,895 of 45,018 says the
+    // share of the corpus that consists of the four kinds the embedder writes.
+    `embeddings: ${e.total} rows / ${e.embeddedEntities} entities / ${e.symbolCoveragePercent}% of symbols`,
+    `models: ${e.models.map((model) => `${model.model}:${model.count}[${model.dimensions.join(",")}]`).join(" ") || "none"}`,
+    `schema: ${report.schema.version ?? "unknown"} (${report.schema.migration ?? "no migration record"}), ${report.schema.tables} tables`,
+    // `indexedFiles=0 errors=0` for a project with no status record is
+    // two zeros that are not measurements. Absence now prints as absence, so
+    // the line cannot be read as a healthy zero next to files=1654.
+    // a recorded shortfall prints as INCOMPLETE, so a half-built index
+    // cannot be skimmed as a normal one.
+    `index: version=${report.indexStatus.indexingVersion ?? "unrecorded"} indexedFiles=${report.indexStatus.indexedFiles ?? "unrecorded"}/${report.indexStatus.totalFilesDiscovered ?? "unrecorded"}${report.indexStatus.isIncomplete ? ` \u2014 INCOMPLETE, ${report.indexStatus.indexShortfall} file(s) found by the walk were never written` : ""}${lastRunCountersOnly ? " (last-run counters, not an index total)" : ""} status=${report.indexStatus.status ?? "unrecorded"} errors=${report.indexStatus.recordPresent ? report.indexStatus.errors.length : "unrecorded"}${report.indexStatus.recordPresent ? "" : " (no brain_index_status row for this project)"}`,
+    // The last INDEX RUN, labelled as such: this is not the cost of the call you
+    // just made, and the two were previously on adjacent lines under a bare
+    // `perf:` with nothing to say which was which.
+    `index run: schemaVersion=${report.performanceStats.schemaVersion ?? "none"} runs=${report.performanceStats.runs.length} latestWallMs=${report.performanceStats.latestRun?.phases?.totalWallMs ?? "n/a"} (the last INDEX RUN, not this call)`,
+    // this call, measured. `total` is the number to act on; the phases
+    // explain it, and are named only when non-zero so a warm call stays short.
+    `this call: ${renderTiming(report.timing)}`,
+    `runtime: ${report.runtime.runtime} ${report.runtime.version} / ${report.runtime.database}`
+  ];
+  if (report.refresh.requested) {
+    const d = report.refresh.derived;
+    const dNote = d === "deferred" ? " \u2014 derived data DEFERRED; run: bb index --post" : d === "bounded" ? " (bounded pass)" : d === "full" ? " (full pass)" : d === "skipped-unchanged" ? " (unchanged \u2014 derived data still consistent)" : "";
+    lines.push(`refresh: ${report.refresh.completed ? "completed" : report.refresh.wait ? "failed" : "started (pending)"} force=${report.refresh.force} wait=${report.refresh.wait} durationMs=${report.refresh.durationMs} derived=${d ?? "n/a (pending/failed)"}${dNote}`);
+  }
+  if (report.unindexed) {
+    lines.push(report.unindexed.unindexedCount > 0 ? `unindexed: ${report.unindexed.unindexedCount} file(s) on disk that the indexer would index are NOT in the index (${report.unindexed.eligibleOnDisk} eligible on disk, ${report.unindexed.indexed} indexed) \u2014 e.g. ${report.unindexed.unindexedFiles.slice(0, 3).join(", ")}${report.unindexed.unindexedCount > 3 ? `, +${report.unindexed.unindexedCount - 3} more` : ""}` : `unindexed: none \u2014 all ${report.unindexed.eligibleOnDisk} indexable file(s) on disk are in the index (excludes files the indexer skips by rule: gitignored, node_modules, unsupported extension, >5MB)`);
+  } else if (report.warnings.some((w) => w.code === "UNINDEXED_SCAN_FAILED")) {
+    lines.push("unindexed: UNKNOWN \u2014 the scan failed, so index completeness is NOT verified");
+  }
+  if (report.analysisRuns) lines.push(`analysis: ${report.analysisRuns.runs} runs / ${report.analysisRuns.findings} findings (both are full-table counts, not page lengths)`);
+  if (report.integrity) {
+    const s = report.integrity.summary;
+    lines.push(`integrity: ${report.integrity.overallHealth}% (${s.error} errors, ${s.warn} warnings, ${s.scored} scored + ${s.informational} informational checks)`);
+    const failing = report.integrity.checks.filter((c2) => c2.status !== "ok");
+    for (const c2 of failing.slice(0, 3)) {
+      const fix = c2.remediation ? ` -> ${firstSentence(c2.remediation)}` : "";
+      lines.push(`  ${c2.status.toUpperCase().padEnd(5)} ${c2.name}: ${firstSentence(c2.description)}${fix}`);
+    }
+    if (failing.length > 3) lines.push(`  \u2026 and ${failing.length - 3} more non-ok check(s); read integrity.checks[] in the JSON for the full set`);
+  }
+  if (report.verbose && report.effectiveConfig) {
+    const ec = report.effectiveConfig;
+    lines.push(`embedding config: ${ec.configured ? "remote provider" : "not configured (local/tfidf fallback)"} \u2014 base-url=${ec.baseURL} (source: ${ec.sources.baseURL}), model=${ec.model} (source: ${ec.sources.model}), api-key source: ${ec.sources.apiKey}${ec.configured ? "" : ""}`);
+    lines.push(`embedding precedence: env BB_EMBEDDING_* > config file (BB_CONFIG_FILE > bb.json > config.json) > default`);
+    if (report.embeddingChain) {
+      lines.push(`embedding chain: ${report.embeddingChain.disabled ? "disabled (BB_EMBEDDING_DISABLED) \u2014 local only" : report.embeddingChain.remoteReady ? "remote ready" : "remote NOT usable"}`);
+      for (const line of renderChainSummary(report.embeddingChain)) lines.push(line);
+      for (const p of report.embeddingChain.problems.filter((x) => !x.message.startsWith("No embedding provider is configured"))) {
+        lines.push(`embedding problem: ${p.envVar ? `${p.envVar}: ` : ""}${p.message}`);
+      }
+      for (const f2 of report.embeddingChain.observedFailures) {
+        lines.push(`embedding failure: ${f2.status} ${f2.kind} from ${f2.baseURL} \u2014 ${f2.advice}`);
+      }
+      if (report.embeddingChain.tierOrderDisagreement) {
+        lines.push(`embedding warning: ${report.embeddingChain.tierOrderDisagreement.detail}`);
+      }
+    }
+  }
+  if (report.verbose) {
+    if (report.languages.length) lines.push(`languages: ${report.languages.map((l) => `${l.language}:${l.files}f/${l.symbols}s`).join(" ")}`);
+    const byLang = report.embeddings.byLanguage.filter((l) => l.symbols > 0);
+    if (byLang.length) {
+      lines.push(`searchable by language: ${byLang.map((l) => `${l.language}:${l.embedded}/${l.symbols}(${l.searchablePercent}%)`).join(" ")}`);
+      const dead = byLang.filter((l) => l.embedded === 0).map((l) => l.language);
+      if (dead.length) lines.push(`unsearchable languages: ${dead.join(", ")} \u2014 no symbol in these has a vector, so bb_ask cannot return them`);
+    }
+    if (report.embeddings.embeddedByEntityType.length) {
+      lines.push(`embedded kinds: ${report.embeddings.embeddedByEntityType.map((k) => `${k.entityType}=${k.count}`).join(" ")}`);
+    }
+    if (report.embeddings.unembeddedKinds.length) {
+      lines.push(`unembedded kinds: ${report.embeddings.unembeddedKinds.map((k) => `${k.kind}=${k.count}`).join(" ")} \u2014 these symbols are NOT semantically searchable (never attempted, not partially covered)`);
+    }
+    lines.push(renderFileList("stale files", report.freshness.staleFiles));
+    lines.push(renderFileList("missing files", report.freshness.missingFiles));
+  }
+  for (const warning of report.warnings) lines.push(`${warning.severity}: [${warning.code}] ${warning.message}`);
+  return [...pre, ...lines].join("\n");
+}
+
+// src/ast/auto-refresh.ts
+import { statSync as statSync2 } from "fs";
+var AUTO_REFRESH_DEFAULTS = { maxFiles: 25, maxBytes: 2 * 1024 * 1024 };
+function autoRefreshEnabled(perCallOptOut) {
+  if (perCallOptOut === true) return false;
+  if (process.env.BB_NO_AUTO_REFRESH === "1") return false;
+  return true;
+}
+function autoRefreshBudget() {
+  const n = Number(process.env.BB_AUTO_REFRESH_MAX_FILES);
+  const b = Number(process.env.BB_AUTO_REFRESH_MAX_BYTES);
+  return {
+    maxFiles: Number.isInteger(n) && n >= 1 ? n : AUTO_REFRESH_DEFAULTS.maxFiles,
+    maxBytes: Number.isFinite(b) && b >= 1 ? b : AUTO_REFRESH_DEFAULTS.maxBytes
+  };
+}
+function collectStaleFiles(raw, rows, statuses) {
+  const staleIds = [...new Set(rows.filter((r) => r.fileId && statuses.get(r.fileId) !== "fresh").map((r) => r.fileId))];
+  const pathById = /* @__PURE__ */ new Map();
+  for (let i = 0; i < staleIds.length; i += 500) {
+    const slice = staleIds.slice(i, i + 500);
+    for (const r of raw.prepare(`SELECT id, path FROM brain_file WHERE id IN (${slice.map(() => "?").join(",")})`).all(...slice)) {
+      pathById.set(r.id, r.path);
+    }
+  }
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of rows) {
+    const key = r.fileId ?? r.filePath ?? "";
+    const status = statuses.get(key);
+    if (!key || !status || status === "fresh") continue;
+    let abs;
+    if (r.fileId) abs = pathById.get(r.fileId);
+    else if (r.filePath && r.filePath.startsWith("/")) abs = r.filePath;
+    if (!abs || seen.has(abs)) continue;
+    seen.add(abs);
+    out.push({ absolutePath: abs, type: status === "missing" ? "deleted" : "modified" });
+  }
+  return out;
+}
+async function maybeAutoRefresh(projectId, projectPath, files, opts = {}) {
+  const modified = files.filter((f) => f.type === "modified");
+  const deleted = files.filter((f) => f.type === "deleted");
+  if (modified.length + deleted.length === 0) return { action: "clean" };
+  if (!autoRefreshEnabled(opts.perCallOptOut)) {
+    return { action: "declined", reason: "disabled", detail: "auto-refresh disabled (BB_NO_AUTO_REFRESH or refresh=false)" };
+  }
+  const { maxFiles, maxBytes } = autoRefreshBudget();
+  const total = modified.length + deleted.length;
+  if (total > maxFiles) {
+    return {
+      action: "declined",
+      reason: "budget-files",
+      detail: `auto-refresh declined: ${total} stale/missing files exceeds the ${maxFiles}-file budget (BB_AUTO_REFRESH_MAX_FILES)`
+    };
+  }
+  let bytes = 0;
+  for (const f of modified) {
+    try {
+      bytes += statSync2(f.absolutePath).size;
+    } catch {
+    }
+  }
+  if (bytes > maxBytes) {
+    return {
+      action: "declined",
+      reason: "budget-bytes",
+      detail: `auto-refresh declined: ${bytes} bytes of modified files exceeds the ${maxBytes}-byte budget (BB_AUTO_REFRESH_MAX_BYTES)`
+    };
+  }
+  const holder = liveIndexLockHolder(projectId);
+  if (holder) {
+    return {
+      action: "declined",
+      reason: "indexer-active",
+      detail: `auto-refresh declined: another index run is active (pid ${holder.pid}, kind=${holder.kind}); answering from existing data with the staleness envelope`
+    };
+  }
+  const t0 = performance.now();
+  try {
+    const r = await reindexFilesParallel(projectId, projectPath, files.map((f) => ({ path: f.absolutePath, type: f.type })));
+    return {
+      action: "refreshed",
+      files: r.indexed,
+      deleted: r.deleted,
+      errors: r.errors,
+      tookMs: Math.round(performance.now() - t0),
+      derivedPass: r.derived?.pass
+    };
+  } catch (e) {
+    if (e instanceof IndexLockHeldError) {
+      return {
+        action: "declined",
+        reason: "indexer-active",
+        detail: `auto-refresh declined: another index run is active (pid ${e.holder.pid}); answering from existing data with the staleness envelope`
+      };
+    }
+    return {
+      action: "declined",
+      reason: "error",
+      detail: `auto-refresh failed: ${String(e?.message ?? e).slice(0, 200)}; answering from existing data with the staleness envelope`
+    };
+  }
+}
+function autoRefreshLine(decision) {
+  if (decision.action === "refreshed") {
+    return `auto-refreshed ${decision.files} file${decision.files === 1 ? "" : "s"}${decision.deleted ? `, removed ${decision.deleted} deleted` : ""} in ${decision.tookMs}ms${decision.derivedPass ? ` (derived pass: ${decision.derivedPass})` : ""}`;
+  }
+  if (decision.action === "declined") return decision.detail;
+  return "";
+}
+
+export {
+  detectOrphans,
+  BrainTools,
+  PatternBrainTools,
+  getAnalysisHistory,
+  executeAnalysis,
+  getUnifiedHealth,
+  formatUnifiedHealth,
+  collectStaleFiles,
+  maybeAutoRefresh,
+  autoRefreshLine
+};