@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/chunk-ZE2LG76D.js

@@ -0,0 +1,1296 @@
+import {
+  BrainTools,
+  autoRefreshLine,
+  collectStaleFiles,
+  formatUnifiedHealth,
+  getUnifiedHealth,
+  maybeAutoRefresh
+} from "./chunk-22V37YTK.js";
+import {
+  IndexLockHeldError,
+  ParallelIndexerConfig,
+  acquireIndexLock,
+  indexProjectParallel
+} from "./chunk-ZETTGPAW.js";
+import {
+  getProjectId
+} from "./chunk-DIYAGQJL.js";
+import {
+  BACKBENCHER_BRAIN_VERSION
+} from "./chunk-WIG36E67.js";
+import {
+  FRESHNESS_REMEDIATION,
+  resolveRowsFreshnessDetailed
+} from "./chunk-QLK6ED4Q.js";
+import {
+  BrainDatabase
+} from "./chunk-QKTRECYS.js";
+import {
+  bold,
+  colorEnabled,
+  cyan,
+  dim,
+  green,
+  red,
+  setLogLevel,
+  yellow
+} from "./chunk-BQ3OVQ3P.js";
+import {
+  bbProjectsDir
+} from "./chunk-2BSKD7O3.js";
+import {
+  describeScopedPathRefusal,
+  resolveScopedProjectFile
+} from "./chunk-D2Q4Y47A.js";
+
+// src/cli/index.ts
+import { Command } from "commander";
+import { fileURLToPath } from "url";
+import { existsSync, realpathSync, statSync } from "fs";
+import path from "path";
+
+// src/cli/index-progress.ts
+var SMALL_PROJECT_FILES = 150;
+var TINY_PROJECT_FILES = 50;
+var ENCOURAGEMENT_MIN_FILES = 50;
+var RATE_WINDOW_MS = 45e3;
+var EXPECTED_MS_PER_FILE = 250;
+var BIG_PROJECT_FILES = 4e3;
+var SLOW_RUN_MS = 3 * 60 * 1e3;
+var SUPPORT_EMAIL = "support@backbencher.cc";
+function encouragementFor(pct, isBigProject2, totalFiles = Number.MAX_SAFE_INTEGER) {
+  if (totalFiles < ENCOURAGEMENT_MIN_FILES) return null;
+  if (pct >= 100) return null;
+  if (pct >= 95) return "almost there \u2014 finishing up";
+  if (pct >= 80) return "in the final stretch";
+  if (pct >= 50) return "past the halfway mark";
+  if (pct >= 25) return "a quarter of the way in";
+  return null;
+}
+function isBigProject(totalFiles) {
+  return totalFiles >= BIG_PROJECT_FILES;
+}
+function formatDuration(ms) {
+  if (ms === null || ms === void 0 || !Number.isFinite(ms) || ms < 0) return "\u2026";
+  const total = Math.floor(ms / 1e3);
+  const h = Math.floor(total / 3600);
+  const m = Math.floor(total % 3600 / 60);
+  const s = total % 60;
+  if (h > 0) return `${h}h ${m}m ${s}s`;
+  if (m > 0) return `${m}m ${s}s`;
+  return `${s}s`;
+}
+function expectationFor(totalFiles) {
+  if (totalFiles <= 0) return "nothing to index \u2014 the index is already up to date";
+  if (totalFiles < TINY_PROJECT_FILES) return "a moment \u2014 this is a tiny project";
+  if (totalFiles < SMALL_PROJECT_FILES) return "this is a small project \u2014 a few minutes at most";
+  if (totalFiles < BIG_PROJECT_FILES) return "this will take a few minutes";
+  return "large project \u2014 this takes a while. Grab a coffee; bb keeps working in the background";
+}
+function countWithCommas(n) {
+  if (n === void 0 || n === null || !Number.isFinite(n)) return "?";
+  return n.toLocaleString();
+}
+function windowedFilesPerSecond(samples, windowMs = RATE_WINDOW_MS) {
+  if (samples.length < 2) return null;
+  const newest = samples[samples.length - 1];
+  const inWindow = samples.filter((s) => newest.at - s.at <= windowMs);
+  const oldest = inWindow.length >= 2 ? inWindow[0] : samples[samples.length - 2];
+  const dt = (newest.at - oldest.at) / 1e3;
+  const df = newest.files - oldest.files;
+  if (dt <= 0.5 || df <= 0) return null;
+  return df / dt;
+}
+function estimateRemainingMs(stats, startedAt, samples = [], now = Date.now()) {
+  const { processedFiles, totalFiles } = stats;
+  if (!totalFiles || processedFiles <= 0) return null;
+  const elapsed = now - startedAt;
+  if (elapsed < 1e3) return null;
+  const remaining = totalFiles - processedFiles;
+  if (remaining <= 0) return 0;
+  const windowed = windowedFilesPerSecond(samples);
+  if (windowed !== null && windowed > 0) {
+    const cumulative = processedFiles / (elapsed / 1e3);
+    const rate = Math.min(windowed, cumulative * 2);
+    if (rate > 0) return remaining / rate * 1e3;
+  }
+  return elapsed / processedFiles * remaining;
+}
+function formatEta(remainingMs, filesDone) {
+  if (remainingMs === null) return "\u2026";
+  if (remainingMs <= 0) return filesDone ? "finishing" : "\u2026";
+  return formatDuration(remainingMs);
+}
+function expectedDurationMs(totalFiles) {
+  return Math.max(SLOW_RUN_MS, totalFiles * EXPECTED_MS_PER_FILE);
+}
+var IndexProgressRenderer = class {
+  stream;
+  isTTY;
+  startedAt;
+  totalFiles;
+  nonTtyIntervalMs;
+  lastRenderAt = 0;
+  lastNonTtyBucket = -1;
+  lastLineLength = 0;
+  announcedExpectation = false;
+  lastEncouragementBand = -1;
+  /** Recent (timestamp, files-done) observations, for the windowed rate. Bounded. */
+  samples = [];
+  /** ANSI allowed for this renderer's stream (TTY, minus NO_COLOR; FORCE_COLOR can opt in). */
+  color;
+  /** Keep only what the window needs, so a long run cannot grow this without bound. */
+  recordSample(files) {
+    const at = Date.now();
+    const last = this.samples[this.samples.length - 1];
+    if (last && last.files === files) return;
+    this.samples.push({ at, files });
+    while (this.samples.length > 2 && at - this.samples[0].at > RATE_WINDOW_MS * 2) this.samples.shift();
+  }
+  constructor(opts) {
+    this.stream = opts.stream;
+    this.isTTY = opts.isTTY;
+    this.startedAt = opts.startedAt;
+    this.totalFiles = opts.totalFiles;
+    this.nonTtyIntervalMs = opts.nonTtyIntervalMs ?? 1e4;
+    this.color = colorEnabled({ isTTY: opts.isTTY });
+  }
+  get elapsedMs() {
+    return Date.now() - this.startedAt;
+  }
+  /** One-time framing line once the file count is known. */
+  begin() {
+    if (this.announcedExpectation) return;
+    const expected = expectationFor(this.totalFiles);
+    this.announcedExpectation = true;
+    this.stream.write(
+      `
+${bold(`Indexing ${countWithCommas(this.totalFiles)} files`, this.color)} \u2014 ${cyan(expected, this.color)}
+
+`
+    );
+  }
+  /**
+   * Render a progress update. Safe to call very frequently; throttling is
+   * internal and differs between TTY and non-TTY.
+   */
+  update(stats) {
+    if (!this.announcedExpectation && stats.totalFiles > 0) {
+      this.totalFiles = stats.totalFiles;
+      this.begin();
+    }
+    this.maybeEncourage(stats);
+    this.recordSample(stats.processedFiles);
+    if (this.isTTY) {
+      const now = Date.now();
+      if (now - this.lastRenderAt < 80) return;
+      this.lastRenderAt = now;
+      this.renderTtyLine(stats);
+      return;
+    }
+    this.renderNonTtyLine(stats);
+  }
+  /**
+   * Print a progress milestone at most once per band. Written ABOVE the live bar
+   * so it does not fight the redraw for the same line.
+   */
+  maybeEncourage(stats) {
+    const total = stats.totalFiles > 0 ? stats.totalFiles : this.totalFiles;
+    if (total <= 0) return;
+    const done = stats.processedFiles + (stats.skippedFiles ?? 0);
+    const pct = Math.min(100, Math.floor(done / total * 100));
+    const line = encouragementFor(pct, isBigProject(total), total);
+    if (!line) return;
+    const band = pct >= 95 ? 95 : pct >= 80 ? 80 : pct >= 50 ? 50 : pct >= 25 ? 25 : 0;
+    if (band === this.lastEncouragementBand) return;
+    this.lastEncouragementBand = band;
+    if (this.isTTY) {
+      this.stream.write(`\r\x1B[2K  ${cyan(line, this.color)}
+`);
+      this.lastLineLength = 0;
+    } else {
+      this.stream.write(`${dim("[index]", this.color)} ${cyan(line, this.color)}
+`);
+    }
+  }
+  renderTtyLine(stats) {
+    const total = stats.totalFiles > 0 ? stats.totalFiles : this.totalFiles;
+    const done = stats.processedFiles + (stats.skippedFiles ?? 0);
+    const pct = total > 0 ? Math.min(100, Math.floor(done / total * 100)) : 0;
+    const rate = typeof stats.filesPerSecond === "number" ? `${stats.filesPerSecond.toFixed(1)}/s` : "?";
+    const remaining = estimateRemainingMs(stats, this.startedAt, this.samples);
+    const filesDone = stats.processedFiles >= total;
+    const eta = formatEta(remaining, filesDone);
+    const elapsed = formatDuration(this.elapsedMs);
+    const BAR = 24;
+    const filled = total > 0 ? Math.round(pct / 100 * BAR) : 0;
+    const bar = "\u2588".repeat(filled) + "\u2591".repeat(BAR - filled);
+    const parts = [
+      `  ${bar} ${bold(String(pct).padStart(3) + "%", this.color)}`,
+      `${countWithCommas(done)}/${countWithCommas(total)} files`,
+      rate,
+      `elapsed ${elapsed}`,
+      bold(cyan(`ETA ${eta}`, this.color), this.color)
+    ];
+    if (stats.symbols !== void 0) parts.push(`${countWithCommas(stats.symbols)} symbols`);
+    if (stats.relationships !== void 0) parts.push(`${countWithCommas(stats.relationships)} rels`);
+    if (stats.embeddings !== void 0) parts.push(`${countWithCommas(stats.embeddings)} embeddings`);
+    let line = parts.join("  ");
+    if (stats.errorFiles) line += `  ${yellow(`\u26A0 ${stats.errorFiles} errors`, this.color)}`;
+    if (stats.currentFile) {
+      const f = stats.currentFile.length > 48 ? "\u2026" + stats.currentFile.slice(-47) : stats.currentFile;
+      line += `  ${f}`;
+    }
+    this.writeTty(line);
+  }
+  writeTty(line) {
+    const pad = this.lastLineLength > line.length ? " ".repeat(this.lastLineLength - line.length) : "";
+    this.stream.write(`\r\x1B[2K${line}${pad}`);
+    this.lastLineLength = line.length + pad.length;
+  }
+  /**
+   * Non-TTY: emit a milestone line, not a redraw. Bucket by completion percentage
+   * AND by wall-clock, so neither a very long run nor a stalled run floods the log.
+   */
+  renderNonTtyLine(stats) {
+    const total = stats.totalFiles > 0 ? stats.totalFiles : this.totalFiles;
+    if (total <= 0) return;
+    const done = stats.processedFiles + (stats.skippedFiles ?? 0);
+    const pct = Math.min(100, Math.floor(done / total * 100));
+    const bucket = Math.floor(pct / 5);
+    const now = Date.now();
+    const dueByBucket = bucket > this.lastNonTtyBucket;
+    const dueByTime = now - this.lastRenderAt >= this.nonTtyIntervalMs;
+    const isFinal = pct >= 100;
+    if (!isFinal && !dueByBucket && !dueByTime) return;
+    if (bucket === this.lastNonTtyBucket) return;
+    this.lastNonTtyBucket = bucket;
+    this.lastRenderAt = now;
+    const remaining = estimateRemainingMs(stats, this.startedAt, this.samples);
+    const eta = formatEta(remaining, stats.processedFiles >= total);
+    this.stream.write(
+      `${dim("[index]", this.color)} ${bold(`${pct}%`, this.color)} ${countWithCommas(done)}/${countWithCommas(total)} files elapsed=${formatDuration(this.elapsedMs)} ${cyan(`eta=${eta}`, this.color)}` + (stats.errorFiles ? ` ${yellow(`errors=${stats.errorFiles}`, this.color)}` : "") + `
+`
+    );
+  }
+  /** Clear the live line before the summary prints. */
+  clear() {
+    if (this.isTTY) {
+      this.stream.write("\r\x1B[2K");
+      this.lastLineLength = 0;
+    }
+  }
+  /**
+   * Post-run messaging. `ok: false` means the run failed — we do not congratulate
+   * the user or suggest a support ticket for a run that did not finish.
+   */
+  finish(result) {
+    this.clear();
+    const elapsed = this.elapsedMs;
+    if (!result.ok) return;
+    const expectedMs = expectedDurationMs(result.totalFiles);
+    if (elapsed >= expectedMs) {
+      this.stream.write(
+        yellow(
+          `
+That took ${formatDuration(elapsed)} \u2014 longer than we expect for ${countWithCommas(result.totalFiles)} files.
+If it felt like it hung, that is worth reporting: ${SUPPORT_EMAIL}
+`,
+          this.color
+        )
+      );
+    } else if (elapsed >= SLOW_RUN_MS) {
+      this.stream.write(
+        yellow(
+          `
+Took ${formatDuration(elapsed)}.
+If this is slower than usual for your project, tell us: ${SUPPORT_EMAIL}
+`,
+          this.color
+        )
+      );
+    }
+  }
+  /** Exposed for the CLI's "nothing to do" fast path. */
+  get didAnnounce() {
+    return this.announcedExpectation;
+  }
+};
+
+// src/cli/index.ts
+function collectList(value, previous) {
+  const out = previous ? [...previous] : [];
+  for (const part of value.split(",")) {
+    const trimmed = part.trim();
+    if (trimmed.length > 0) out.push(trimmed);
+  }
+  return out;
+}
+function requireDir(p) {
+  const abs = path.resolve(p);
+  if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+    console.error(`\u2717 not a directory: ${abs}`);
+    process.exit(1);
+  }
+  return abs;
+}
+async function cmdIndex(dir, opts) {
+  const abs = dir ? requireDir(dir) : process.cwd();
+  const S = colorEnabled({ isTTY: process.stdout.isTTY });
+  const { maybeRunFirstRunSetup } = await import("./setup-wizard-G5YYR5T6.js");
+  await maybeRunFirstRunSetup({ noSetup: opts.noSetup === true });
+  const pid = getProjectId(abs);
+  {
+    const f = {
+      force: opts.force === true,
+      changed: opts.changed === true,
+      resume: opts.resume === true,
+      post: opts.post === true,
+      skipPost: opts.skipPostProcessing === true,
+      file: opts.file != null,
+      imp: opts.import != null
+    };
+    const LEGAL = [
+      { when: (x) => !x.force && !x.changed && !x.resume && !x.post && !x.skipPost && !x.file && !x.imp, behavior: "full index + all post-processing" },
+      { when: (x) => x.changed && !x.force && !x.resume && !x.post && !x.skipPost && !x.file && !x.imp, behavior: "incremental parse + bounded post-pass" },
+      { when: (x) => x.resume && !x.force && !x.changed && !x.post && !x.skipPost && !x.file && !x.imp, behavior: "incremental from checkpoint + bounded post-pass" },
+      { when: (x) => x.post && !x.force && !x.changed && !x.resume && !x.skipPost && !x.file && !x.imp, behavior: "no parse; re-run 5 derived phases only" },
+      { when: (x) => x.skipPost && !x.force && !x.changed && !x.resume && !x.post && !x.file && !x.imp, behavior: "parse+store only; derived data deferred (bb index --post to finish)" },
+      { when: (x) => x.file && !x.force && !x.changed && !x.resume && !x.post && !x.skipPost && !x.imp, behavior: "single-file reindex + scoped post-pass" },
+      { when: (x) => x.imp && !x.force && !x.changed && !x.resume && !x.post && !x.skipPost && !x.file, behavior: "adopt DB, then incremental top-up" },
+      { when: (x) => x.force && !x.changed && !x.resume && !x.post && !x.skipPost && !x.file && !x.imp, behavior: "wipe + full index + full post-processing" }
+    ];
+    if (!LEGAL.some((l) => l.when(f))) {
+      const active = Object.entries(f).filter(([, v]) => v).map(([k]) => `--${k === "skipPost" ? "skip-post-processing" : k === "imp" ? "import" : k}`).join(" ");
+      console.error(`\u2717 conflicting bb index options: ${active || "(none)"}
+  This combination has no defined behavior. See the semantics matrix: bb index --help, docs/m40/PLAN.md
+  Remediations: --force alone rebuilds everything; --post alone re-runs derived-data phases; --changed/--resume alone run the bounded pass.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  if (opts.concurrency !== void 0) {
+    const n = Number(opts.concurrency);
+    if (!Number.isInteger(n) || n < 1 || n > 64) {
+      console.error(`\u2717 --concurrency expects an integer 1-64 (got ${JSON.stringify(opts.concurrency)})`);
+      process.exitCode = 1;
+      return;
+    }
+    ParallelIndexerConfig.concurrency = n;
+  }
+  const excludeGlobs = Array.isArray(opts.exclude) ? opts.exclude : [];
+  let resolvedScopedFile = null;
+  if (opts.file) {
+    const resolved = resolveScopedProjectFile(abs, opts.file);
+    if (!resolved.ok) {
+      console.error(`\u2717 ${describeScopedPathRefusal(resolved)}`);
+      process.exitCode = 1;
+      return;
+    }
+    resolvedScopedFile = resolved.absolute;
+  }
+  if (opts.post) {
+    const { runPostProcessing } = await import("./parallel-indexer-FK2XKZXY.js");
+    try {
+      const post = await runPostProcessing(pid);
+      console.log(`\u2713 post-processing complete in ${(post.totalMs / 1e3).toFixed(1)}s`);
+      for (const p of post.phases) {
+        console.log(`  ${p.outcome === "ok" ? "\u2713" : p.outcome === "failed" ? "\u2717" : "-"} ${p.name.padEnd(14)} ${p.ms}ms`);
+      }
+      const failedPhases = post.phases.filter((p) => p.outcome === "failed");
+      if (failedPhases.length > 0) {
+        console.error(`\u2717 ${failedPhases.length} post-processing phase(s) failed (${failedPhases.map((p) => p.name).join(",")}) \u2014 index marked partial`);
+        process.exitCode = 1;
+      }
+    } catch (e) {
+      console.error(`\u2717 post-processing failed: ${e?.message}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (opts.import != null) {
+    const { importDbFile } = await import("./project-registry-ZJ3DVUGO.js");
+    const result = importDbFile(opts.import, pid, abs);
+    if (result.adopted) {
+      console.log(`imported ${opts.import} as project ${pid.slice(0, 8)} (index rebound to this checkout)`);
+      return;
+    }
+    console.error(`\u2717 import failed: ${result.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  let adopted = false;
+  if (!opts.force) {
+    const dbPath = BrainDatabase.getDbPath(pid);
+    if (!existsSync(dbPath)) {
+      const { findAdoptableDb, adoptProject } = await import("./project-registry-ZJ3DVUGO.js");
+      const { computeCheckoutFingerprint } = await import("./fingerprint-OBLIMZLP.js");
+      const cf = await computeCheckoutFingerprint(abs);
+      if (cf.fingerprint) {
+        const candidate = findAdoptableDb(cf.fingerprint);
+        if (candidate) {
+          const result = adoptProject(candidate.id, pid, abs);
+          if (result.adopted) {
+            adopted = true;
+            console.log(`adopted existing index from project ${candidate.id.slice(0, 8)} (moved/rebound to ${pid.slice(0, 8)})`);
+          } else {
+            console.warn(`adoption failed: ${result.reason}`);
+          }
+        }
+      }
+    }
+  }
+  console.log(bold(`indexing ${abs} (project ${pid.slice(0, 8)}\u2026)`, S));
+  if (process.stdout.isTTY) console.log(dim("  scanning project files\u2026", S));
+  let heldLock = null;
+  if (opts.force) {
+    try {
+      heldLock = await acquireIndexLock(pid, { kind: "wipe+index" });
+    } catch (e) {
+      if (e instanceof IndexLockHeldError) {
+        console.error(`\u2717 ${e.message}`);
+      } else {
+        console.error(`\u2717 could not acquire the index lock: ${e?.message}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const { wipeProjectData } = await import("./parallel-indexer-FK2XKZXY.js");
+      const raw = await BrainDatabase.getRawInstance(pid);
+      const wiped = wipeProjectData(raw);
+      console.log(`wiped ${pid.slice(0, 8)} index in place (file kept)`);
+      const { reclaimSpace, formatSpace, shouldVacuumAfterWipe } = await import("./index-space-IUUN5WYV.js");
+      const dbBytes = statSync(BrainDatabase.getDbPath(pid)).size;
+      const space = reclaimSpace(raw, BrainDatabase.getDbPath(pid), {
+        vacuum: shouldVacuumAfterWipe({ rowsDeleted: wiped.rowsDeleted, dbBytes }),
+        vacuumAboveRatio: 0,
+        vacuumAboveBytes: 0,
+        log: (message, meta) => console.log(`  ${message}${meta ? ` ${JSON.stringify(meta)}` : ""}`)
+      });
+      console.log(`  index space: ${formatSpace(space)}`);
+    } catch (e) {
+      console.error(`\u2717 wipe failed: ${e?.message}`);
+    }
+  }
+  const t = Date.now();
+  const indexOpts = { onProgress: (s) => {
+  } };
+  if (excludeGlobs.length > 0) indexOpts.excludePatterns = excludeGlobs;
+  if (opts.skipPostProcessing) indexOpts.skipPostProcessing = true;
+  if (opts.file) {
+    indexOpts.files = [resolvedScopedFile];
+    indexOpts.isIncremental = true;
+  }
+  if (opts.changed) indexOpts.isIncremental = true;
+  if (adopted) indexOpts.isIncremental = true;
+  if (opts.resume) {
+    const { readLiveStatus } = await import("./index-status-7OVGYSGW.js");
+    const ck = readLiveStatus(pid);
+    const inProgress = !!ck && (ck.phase === "indexing" || ck.phase === "cancelled") && Date.now() - ck.updatedAt < 36e5;
+    if (inProgress) {
+      console.log(`resuming interrupted index (checkpoint: ${ck.processedFiles}/${ck.totalFiles} files done)`);
+    } else {
+      console.log("no in-progress checkpoint; running incremental (only missing/changed files)");
+    }
+    indexOpts.isIncremental = true;
+  }
+  const progress = new IndexProgressRenderer({
+    stream: process.stderr,
+    isTTY: Boolean(process.stderr.isTTY),
+    startedAt: t,
+    totalFiles: 0
+  });
+  indexOpts.onProgress = (s) => {
+    progress.update({
+      processedFiles: Number(s.processedFiles ?? 0),
+      totalFiles: Number(s.totalFiles ?? 0),
+      skippedFiles: Number(s.skippedFiles ?? 0),
+      errorFiles: Number(s.errorFiles ?? 0),
+      currentFile: s.currentFile ?? "",
+      filesPerSecond: typeof s.filesPerSecond === "number" ? s.filesPerSecond : void 0,
+      symbols: typeof s.symbols === "number" ? s.symbols : void 0,
+      relationships: typeof s.relationships === "number" ? s.relationships : void 0,
+      embeddings: typeof s.embeddings === "number" ? s.embeddings : void 0
+    });
+  };
+  const abort = new AbortController();
+  const onSignal = (sig) => {
+    if (abort.signal.aborted) return;
+    abort.abort();
+    console.log(`
+${sig} received \u2014 cancelling index (draining in-flight files; resume with: bb index --resume)...`);
+  };
+  if (heldLock) indexOpts.lock = heldLock;
+  let stats;
+  try {
+    process.once("SIGINT", () => onSignal("SIGINT"));
+    process.once("SIGTERM", () => onSignal("SIGTERM"));
+    indexOpts.signal = abort.signal;
+    stats = await indexProjectParallel(pid, abs, indexOpts);
+  } catch (e) {
+    process.removeAllListeners("SIGINT");
+    process.removeAllListeners("SIGTERM");
+    if (heldLock) await heldLock.release().catch(() => {
+    });
+    if (e instanceof IndexLockHeldError) {
+      console.error(`\u2717 ${e.message}`);
+    } else if (abort.signal.aborted) {
+      progress.clear();
+      console.log("\u23F8 index cancelled before parsing started \u2014 no files were written. Re-run when ready: bb index");
+      process.exitCode = 130;
+      return;
+    } else {
+      throw e;
+    }
+    process.exitCode = 1;
+    return;
+  }
+  process.removeAllListeners("SIGINT");
+  process.removeAllListeners("SIGTERM");
+  progress.clear();
+  const secs = ((Date.now() - t) / 1e3).toFixed(1);
+  const db = await BrainDatabase.getRawInstance(pid);
+  const { pendingEmbeddingCount, embeddingDrainPending, flushBackgroundEmbeddings } = await import("./parallel-indexer-FK2XKZXY.js");
+  const pendingAtEnd = pendingEmbeddingCount();
+  if (embeddingDrainPending()) {
+    const waitMs = Number(process.env.BB_EMBEDDING_DRAIN_WAIT_MS || 3e5);
+    const waitSecs = Math.round(waitMs / 1e3);
+    console.log(
+      pendingAtEnd > 0 ? `  finishing ${pendingAtEnd.toLocaleString()} embedding(s) \u2014 the index and its relationships are already complete; these are vectors (waiting up to ${waitSecs}s)` : `  finishing embedding work \u2014 the index and its relationships are already complete; vectors are still being written (waiting up to ${waitSecs}s)`
+    );
+    const drain = await flushBackgroundEmbeddings({ timeoutMs: waitMs });
+    if (drain.resolved === "drained") {
+      console.log("  \u2713 embedding queue drained");
+    } else {
+      console.log(
+        `  \u26A0 ${drain.pendingItems.toLocaleString()} embedding(s) still queued after ${waitSecs}s \u2014 semantic search is partial for those symbols; run \`bb index --changed\` to finish them`
+      );
+    }
+  }
+  const files = db.prepare("SELECT COUNT(*) c FROM brain_file").get().c;
+  const symbols = db.prepare("SELECT COUNT(*) c FROM brain_symbol").get().c;
+  const rels = db.prepare("SELECT COUNT(*) c FROM brain_relationship").get().c;
+  const emb = db.prepare("SELECT COUNT(*) c FROM brain_semantic_embedding").get().c;
+  const { reclaimSpace: reclaimEndSpace, formatSpace: formatEndSpace } = await import("./index-space-IUUN5WYV.js");
+  const endSpace = reclaimEndSpace(db, BrainDatabase.getDbPath(pid), { vacuum: false });
+  console.log(dim(`  index space: ${formatEndSpace(endSpace)}`, S));
+  if (!stats.cancelled) {
+    try {
+      const { runIndexHealthCheck } = await import("./brain-index-health-Q5APTJQL.js");
+      const finalHealth = await runIndexHealthCheck(pid);
+      const problemChecks = finalHealth.checks.filter((c) => c.status === "error" || c.status === "warn");
+      if (problemChecks.length === 0) {
+        console.log(green(`  \u2705 index health (after embeddings): ${finalHealth.overallHealth}% \u2014 all checks passed`, S));
+      } else {
+        console.log(
+          yellow(`  \u26A0\uFE0F  index health (after embeddings): ${finalHealth.overallHealth}% \u2014 ${problemChecks.length} warning(s) (run bb health for details)`, S)
+        );
+        for (const c of finalHealth.checks) {
+          if (c.status === "error") console.log(red(`    \u274C ${c.name}: ${c.description}`, S));
+        }
+      }
+    } catch (healthErr) {
+      console.log(`  \u26A0 index health could not be re-checked after the embedding drain: ${healthErr?.message ?? healthErr}`);
+    }
+  }
+  const parsedNothing = Number(stats.summary?.newlyParsed ?? 0) === 0 && !stats.cancelled;
+  const missing = Number(stats.summary?.missingAfterRecovery ?? 0);
+  const storeFailures = Number(stats.summary?.storeFailures ?? 0);
+  if (missing > 0) {
+    console.log(
+      yellow(
+        `\u26A0 indexed ${files} files \u2014 but ${missing} of the ${stats.totalFiles} discovered file(s) could NOT be stored (${storeFailures} store batch(es) rolled back). The index is INCOMPLETE.`,
+        S
+      )
+    );
+    console.log(
+      dim(`  This is a write failure, not a parse failure: check free disk space and that the database is writable, then re-run.`, S)
+    );
+    process.exitCode = 1;
+  } else if (parsedNothing) {
+    const unchanged = Number(stats.summary?.unchanged ?? 0);
+    const skipped = Number(stats.summary?.skipped ?? 0);
+    console.log(
+      green(`\u2713 nothing to index \u2014 already up to date (${unchanged} unchanged, ${skipped} skipped, ${secs}s)`, S)
+    );
+  } else {
+    console.log(green(bold(`\u2713 indexed ${files} files, ${symbols} symbols, ${rels} relationships, ${emb} embeddings in ${secs}s`, S), S));
+    if (process.stdout.isTTY) console.log(dim("  Evidence is the answer \u2014 every number above was recorded by this run.", S));
+  }
+  if (missing === 0 && storeFailures > 0) {
+    console.log(dim(`  note: ${storeFailures} store batch(es) rolled back and were recovered \u2014 the index is complete`, S));
+  }
+  console.log(dim(`  stats: ${JSON.stringify({ totalFiles: stats.totalFiles, processed: stats.processedFiles, errors: stats.errorFiles })}`, S));
+  const embOutcome = stats.summary?.embedOutcome;
+  if (embOutcome && (embOutcome.failed > 0 || embOutcome.invalid > 0 || embOutcome.dropped > 0)) {
+    const parts = [];
+    if (embOutcome.embedded > 0) parts.push(`${embOutcome.embedded} embedded`);
+    if (embOutcome.failed > 0) parts.push(`${embOutcome.failed} failed`);
+    if (embOutcome.invalid > 0)
+      parts.push(`${embOutcome.invalid} discarded as malformed (non-finite or empty)`);
+    if (embOutcome.dropped > 0) parts.push(`${embOutcome.dropped} dropped (queue cap)`);
+    console.log(`  embeddings incomplete: ${parts.join(", ")}`);
+    console.log(`    semantic search is degraded \u2014 run \`bb doctor\` to check the embedding provider`);
+  }
+  const embModels = db.prepare(
+    `SELECT embedding_model AS model, vector_dimension AS dimension, COUNT(*) AS count
+         FROM brain_semantic_embedding
+        GROUP BY embedding_model, vector_dimension
+        ORDER BY count DESC`
+  ).all();
+  if (embModels.length > 1) {
+    console.log(
+      `  \u26A0 index holds ${embModels.length} embedding models \u2014 bb_ask searches only one, so the rest are ignored:`
+    );
+    for (const m of embModels) {
+      console.log(`      ${m.model} (${m.dimension}d): ${m.count.toLocaleString()} vectors`);
+    }
+    console.log(`    fix: reindex with one provider \u2014 \`bb index --force\``);
+  } else if (embModels.length === 1) {
+    console.log(`  embeddings: ${embModels[0].model} (${embModels[0].dimension}d)`);
+  }
+  const integ = stats.summary?.embeddingIntegrity;
+  if (integ) {
+    if (integ.unusableEmbeddings > 0) {
+      console.log(
+        `  \u26A0 ${integ.unusableEmbeddings} of ${integ.total.toLocaleString()} vectors are unusable (${integ.dimensionMismatches} length mismatch, ${integ.malformedVectors} malformed)`
+      );
+      console.log(
+        `    these are counted as coverage but unreachable by search \u2014 fix: \`bb index --force\``
+      );
+    }
+    if (integ.truncated) {
+      console.log(
+        `    (integrity census scanned ${(integ.scanned ?? 0).toLocaleString()} of ${integ.total.toLocaleString()} vectors)`
+      );
+    }
+  }
+  progress.finish({
+    ok: !stats.cancelled,
+    totalFiles: Number(stats.totalFiles ?? 0),
+    errorCount: Number(stats.errorFiles ?? 0),
+    cancelled: Boolean(stats.cancelled)
+  });
+  if (stats.cancelled) {
+    console.log(`\u23F8 index cancelled after ${secs}s \u2014 progress saved. Resume with: bb index --resume`);
+  }
+  if (stats.summary) {
+    const s = stats.summary;
+    console.log(`  breakdown: ${s.newlyParsed} newly parsed | ${s.unchanged} unchanged | ${s.skipped} skipped | ${s.symbolLoss} symbol-loss (parsed 0 symbols) | ${s.errors} errors | ${s.timeouts} timeouts${s.cancelled ? ` | ${s.cancelled} cancelled` : ""}`);
+    const parseMode = s.parseMode;
+    const parsedAnything = Number(s.newlyParsed ?? 0) > 0;
+    if (!parsedAnything) {
+      console.log("  parsed nothing \u2014 no files needed parsing, so no parse mode was used");
+    } else if (parseMode === "in-process") {
+      console.log("  parsed in-process \u2014 the worker pool was unavailable, so this run was serial and is correspondingly slower");
+    } else if (parseMode === "worker-pool") {
+      console.log("  parsed with the worker pool");
+    } else {
+      console.log("  parsed: mode not recorded for this run (pre-dates the parseMode field)");
+    }
+    const derived = s.derivedPass ?? "deferred";
+    const unresolved = Number(s.unresolvedRelationships ?? -1);
+    const derivedNote = {
+      full: "derived data fully re-processed",
+      bounded: "derived data re-processed for touched files (bounded pass)",
+      deferred: "derived data deferred \u2014 run: bb index --post",
+      "skipped-unchanged": "no files parsed, so no derived pass ran",
+      // A derived phase threw. MEASURED with a fault injected into the resolution
+      // pass: the run used to print "full (derived data fully re-processed)" with
+      // a WARN in the log and exit 0, and `bb index --post` printed the same
+      // condition as a success. Same remediation as stale derived data.
+      partial: "at least one derived phase FAILED, so the derived data is incomplete"
+    };
+    console.log(`  derived: ${derived} (${derivedNote[derived] ?? derived})`);
+    if (derived === "partial") {
+      console.error("  \u2717 a derived phase failed \u2014 index marked partial. Run: bb index --post");
+      process.exitCode = 1;
+    }
+    if (unresolved === 0) {
+      console.log(
+        "  consistency: every internal relationship is attached to a symbol (external references are attached to an external identity, which is correct)"
+      );
+    } else if (unresolved > 0) {
+      console.log(
+        `  consistency: ${unresolved} internal relationship(s) are attached to neither a symbol nor an external reference \u2014 they are counted above but read as edges by no traversal. Run: bb index --post`
+      );
+    } else {
+      console.log("  consistency: not measured for this run (pre-dates the unresolved-relationship count)");
+    }
+    if (stats.m40Bounded) {
+      const b = stats.m40Bounded;
+      const parts = [`${b.touchedSymbols} symbols touched`];
+      if (b.repairedInEdges > 0) parts.push(`${b.repairedInEdges} cross-file edges restored`);
+      if (b.purgedDeletedFiles > 0) parts.push(`${b.purgedDeletedFiles} deleted files purged`);
+      console.log(`  bounded: ${parts.join(" | ")}`);
+    }
+  }
+  if (heldLock) await heldLock.release().catch(() => {
+  });
+}
+async function cmdSearch(query, opts) {
+  const dir = opts.dir ? requireDir(opts.dir) : process.cwd();
+  const pid = getProjectId(dir);
+  const dbPath = BrainDatabase.getDbPath(pid);
+  if (!existsSync(dbPath)) {
+    console.error(`\u2717 no index for ${dir}. Run: bb index "${dir}"`);
+    process.exit(1);
+  }
+  const KNOWN_MODES = /* @__PURE__ */ new Set(["symbols", "content", "symbol", "file"]);
+  if (opts.mode !== void 0 && !KNOWN_MODES.has(opts.mode)) {
+    console.error(`\u2717 unknown search mode "${opts.mode}" (known: symbols, content, symbol, file)`);
+    process.exit(1);
+  }
+  if (opts.language !== void 0) {
+    const { ASTEngine } = await import("./engine-VIW6NSKO.js");
+    if (!ASTEngine.isSupportedLanguage(opts.language)) {
+      console.error(
+        `\u2717 unknown language "${opts.language}". Run \`bb index --help\` for supported languages, or \`bb projects\` to see which are in this index.`
+      );
+      process.exit(1);
+    }
+  }
+  const mode = opts.mode ?? "symbols";
+  if (mode !== "symbols") {
+    const { createToolHandlers } = await import("./tool-handlers-OJDC35DI.js");
+    const handler = createToolHandlers()["bb_search"];
+    const args = mode === "file" ? { mode: "file", filePath: opts.filePath ?? query } : mode === "symbol" ? { mode: "symbol", symbolName: opts.symbolName ?? query, filePath: void 0, ...opts.noAutoRefresh ? { refresh: false } : {} } : { mode: "content", query, limit: opts.limit ?? 15, language: opts.language, ...opts.noAutoRefresh ? { refresh: false } : {} };
+    const res = await handler(args, { projectId: pid, projectPath: dir });
+    if (res.isError) {
+      console.error(res.content.map((c) => c.text).join("\n"));
+      process.exitCode = 1;
+      return;
+    }
+    const parsed = JSON.parse(res.content[0].text);
+    if (mode === "content") {
+      for (const r of parsed.results ?? []) {
+        const stale = r.stale ? " \u26A0stale" : "";
+        console.log(`  ${path.posix.basename(String(r.fileId ?? r.file ?? ""))}:${r.line ?? "?"} \u2014 ${String(r.snippet ?? r.text ?? "").split("\n")[0].slice(0, 120)}${stale}`);
+      }
+      const env = parsed.freshness ?? {};
+      console.log(`
+${parsed.total} results${parsed.staleCount ? ` (${parsed.staleCount} stale)` : ""}${env.stale != null ? ` | freshness: ${env.fresh} fresh / ${env.stale} stale / ${env.missing} missing` : ""}${parsed.staleCount ? ` \u2014 ${FRESHNESS_REMEDIATION.dir}` : ""}`);
+    } else if (mode === "symbol") {
+      for (const m of parsed.matches ?? []) {
+        const stale = m.stale ? " \u26A0stale" : "";
+        const symType = m.symbolType ?? m.type;
+        const line = m.lineStart ?? m.line;
+        const file = m.fileId ?? m.file ?? "";
+        const lang = m.language ?? "";
+        const loc = lang ? `${lang}, ${path.posix.basename(String(file))}:${line ?? "?"}` : `${path.posix.basename(String(file))}:${line ?? "?"}`;
+        console.log(`  ${m.name}${symType ? ` [${symType}]` : ""} (${loc})${stale}`);
+      }
+      const env = parsed.freshness ?? {};
+      if (env.stale != null) console.log(`
+freshness: ${env.fresh} fresh / ${env.stale} stale / ${env.missing} missing \u2014 ${env.remediation ?? ""}`);
+      if ((parsed.matches ?? []).length === 0) console.log(`no results for "${opts.symbolName ?? query}"`);
+    } else {
+      console.log(`${parsed.file} (${parsed.language})${parsed.truncated ? " [truncated]" : ""}${parsed.stale ? " \u26A0stale" : ""}
+
+${parsed.content}`);
+      const env = parsed.freshness ?? {};
+      if (env.stale != null) console.log(`
+freshness: ${env.fresh} fresh / ${env.stale} stale / ${env.missing} missing \u2014 ${env.remediation ?? ""}`);
+    }
+    if (typeof parsed.autoRefresh === "string" && parsed.autoRefresh.length) console.log(parsed.autoRefresh);
+    return;
+  }
+  const runPass = async () => {
+    const results = await BrainTools.searchCode(pid, query, {
+      maxResults: opts.limit ?? 15,
+      languages: opts.language ? [opts.language] : void 0
+    });
+    const lines = [];
+    for (const r of results) {
+      const stale = r.stale ? " \u26A0stale" : "";
+      lines.push(`  ${r.symbolName} [${r.symbolType}] (${r.language}, ${r.file}:${r.line})${stale}`);
+    }
+    return { results, lines };
+  };
+  const pass1 = await runPass();
+  if (pass1.results.length === 0) {
+    console.log(`no results for "${query}"`);
+    return;
+  }
+  let footer = `
+${pass1.results.length} results${pass1.results.staleCount ? ` (${pass1.results.staleCount} stale \u2014 ${FRESHNESS_REMEDIATION.dir})` : ""}`;
+  let decision = null;
+  if ((pass1.results.staleCount ?? 0) > 0 && !opts.noAutoRefresh) {
+    const raw = await BrainDatabase.getRawInstance(pid);
+    const rows = pass1.results.map((r) => ({ fileId: r.fileId }));
+    const detail = resolveRowsFreshnessDetailed(raw, pid, rows);
+    const staleFiles = collectStaleFiles(raw, rows, detail.statuses);
+    if (staleFiles.length > 0) {
+      const d = await maybeAutoRefresh(pid, dir, staleFiles, { perCallOptOut: false });
+      if (d.action === "refreshed") {
+        const pass2 = await runPass();
+        decision = autoRefreshLine(d);
+        for (const line of pass2.lines) console.log(line);
+        if (pass2.results.length === 0) console.log(`no results for "${query}"`);
+        else console.log(`
+${pass2.results.length} results`);
+        console.log(decision);
+        return;
+      }
+      if (d.action === "declined") decision = autoRefreshLine(d);
+    }
+  }
+  for (const line of pass1.lines) console.log(line);
+  console.log(footer);
+  if (decision && !footer.includes(decision)) console.log(decision);
+}
+async function cmdStats(dir, opts = {}) {
+  const abs = dir ? requireDir(dir) : process.cwd();
+  const pid = getProjectId(abs);
+  const { composeStatus } = await import("./index-status-7OVGYSGW.js");
+  const s = await composeStatus(pid);
+  if (!s.hasIndex) {
+    if (opts.json) console.log(JSON.stringify({ dir: abs, projectId: pid, hasIndex: false }, null, 2));
+    else console.error(`no index for ${abs}. Run: bb index "${abs}"`);
+    process.exitCode = 1;
+    return;
+  }
+  let embeddings = 0;
+  try {
+    const r = await BrainDatabase.getRawInstance(pid);
+    embeddings = r.prepare("SELECT COUNT(*) c FROM brain_semantic_embedding").get()?.c ?? 0;
+  } catch {
+  }
+  const dbPath = BrainDatabase.getDbPath(pid);
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          dir: abs,
+          projectId: pid,
+          hasIndex: true,
+          files: s.dbStats.files,
+          symbols: s.dbStats.symbols,
+          relationships: s.dbStats.relationships,
+          embeddings,
+          dbPath
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  console.log(`index stats for ${abs}:`);
+  console.log(`  files ${s.dbStats.files} | symbols ${s.dbStats.symbols} | relationships ${s.dbStats.relationships} | embeddings ${embeddings}`);
+  console.log(`  db: ${dbPath}`);
+}
+async function cmdProjects(opts) {
+  const { listProjects, removeProject, totalProjectsBytes } = await import("./project-registry-ZJ3DVUGO.js");
+  if (opts.remove) {
+    const r = removeProject(opts.remove, opts.force === true);
+    if (opts.json) console.log(JSON.stringify({ removed: r.removed, projectId: opts.remove, reason: r.removed ? null : r.reason }, null, 2));
+    else if (r.removed) console.log(`removed project ${opts.remove.slice(0, 8)} (index reclaimed)`);
+    else console.error(`\u2717 ${r.reason}`);
+    process.exitCode = r.removed ? 0 : 1;
+    return;
+  }
+  const projects = listProjects();
+  if (projects.length === 0) {
+    if (opts.json) console.log(JSON.stringify({ dataDir: bbProjectsDir(), count: 0, totalBytes: 0, projects: [] }, null, 2));
+    else console.log("no indexed projects");
+    return;
+  }
+  const sort = opts.sort ?? "name";
+  projects.sort((a, b) => sort === "size" ? b.dbSizeBytes - a.dbSizeBytes : sort === "time" ? (b.lastIndexed ?? 0) - (a.lastIndexed ?? 0) : a.id.localeCompare(b.id));
+  const mb = (b) => `${(b / 1024 / 1024).toFixed(1)}MB`;
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          dataDir: bbProjectsDir(),
+          count: projects.length,
+          totalBytes: totalProjectsBytes(projects),
+          projects
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  const when = (t) => t ? new Date(t).toISOString().slice(0, 10) : "n/a";
+  for (const p of projects) {
+    const where = p.humanPath ?? "(no path recorded)";
+    const counts = p.unreadable ? `UNREADABLE (${p.unreadable})` : `${p.files} files ${p.symbols} syms`;
+    console.log(`${p.id.slice(0, 8)} | ${counts} | ${mb(p.dbSizeBytes)} | idx ${when(p.lastIndexed)} | ${p.status ?? ""} | ${where} | db: ${p.dbPath}`);
+  }
+  const unreadableCount = projects.filter((p) => p.unreadable !== null).length;
+  console.log(`
+${projects.length} projects, ${mb(totalProjectsBytes(projects))} total index size (${bbProjectsDir()})`);
+  if (unreadableCount > 0) {
+    console.log(
+      `${unreadableCount} of ${projects.length} could not be read; re-index them (bb index <path>) \u2014 their file/symbol counts are unknown, not zero`
+    );
+  }
+}
+async function cmdStatus(dir, opts = {}) {
+  const abs = dir ? requireDir(dir) : process.cwd();
+  const pid = getProjectId(abs);
+  const { composeStatus } = await import("./index-status-7OVGYSGW.js");
+  const s = await composeStatus(pid);
+  if (!s.hasIndex) {
+    if (opts.json) console.log(JSON.stringify({ dir: abs, projectId: pid, hasIndex: false }, null, 2));
+    else console.error(`no index for ${abs}. Run: bb index "${abs}"`);
+    process.exitCode = 1;
+    return;
+  }
+  const dbPath = BrainDatabase.getDbPath(pid);
+  if (opts.json) {
+    console.log(JSON.stringify({ dir: abs, projectId: pid, dbPath, ...s }, null, 2));
+    return;
+  }
+  const ms = (v) => typeof v === "number" ? `${v}ms` : "n/a";
+  if (s.isRunning && s.live) {
+    const l = s.live;
+    const total = l.totalFiles > 0 ? l.totalFiles : l.processedFiles;
+    const pct = l.totalFiles > 0 ? Math.floor(l.processedFiles / l.totalFiles * 100) : 0;
+    const elapsed = ((Date.now() - l.startedAt) / 1e3).toFixed(0);
+    console.log(`\u25B6 indexing ${abs}: ${l.processedFiles}/${total} files (${pct}%) in ${elapsed}s${typeof l.filesPerSecond === "number" ? ` @ ${l.filesPerSecond.toFixed(1)} files/s` : ""}${l.currentFile ? ` \u2014 ${l.currentFile}` : ""}`);
+    console.log(`  phase: ${l.phase}`);
+  } else if (s.lastRun) {
+    const r = s.lastRun;
+    console.log(`\u2713 last index of ${abs}: ${s.dbStats.files} files, ${s.dbStats.symbols} symbols, ${s.dbStats.relationships} relationships`);
+    const t = r.phaseTimings ?? {};
+    console.log(`  total ${ms(t.totalWallMs)} | parse ${ms(t.parseMs)} | dbFlush ${ms(t.dbFlushMs)} | discovery ${ms(t.discoveryMs)} | startup ${ms(t.workerStartupMs)}`);
+    if (Array.isArray(r.postProcessing) && r.postProcessing.length) {
+      console.log(`  post-processing: ${r.postProcessing.map((p) => `${p.phase ? p.phase : "?"}=${ms(p.ms)}`).join(", ")}`);
+    }
+    console.log(`  mode ${r.mode ?? "n/a"} | workers ${r.workerCount ?? "n/a"} | noop ${r.noop ? "yes" : "no"}`);
+  } else {
+    console.log(`index meta: ${s.dbStats.files} files, ${s.dbStats.symbols} symbols, ${s.dbStats.relationships} relationships (no recent run)`);
+  }
+  console.log(`  db: ${BrainDatabase.getDbPath(pid)}`);
+}
+async function cmdHealth(dir, opts) {
+  const abs = dir ? requireDir(dir) : process.cwd();
+  const pid = getProjectId(abs);
+  const dbPath = BrainDatabase.getDbPath(pid);
+  if (!existsSync(dbPath)) {
+    console.error(`\u2717 no index for ${abs}. Run: bb index "${abs}"`);
+    process.exit(1);
+  }
+  const report = await getUnifiedHealth(pid, abs, {
+    refresh: opts.refresh === true || opts.force === true,
+    force: opts.force === true,
+    wait: opts.wait !== false,
+    freshness: opts.complete === true ? "complete" : "sampled",
+    sampleSize: opts.sampleSize,
+    integrity: opts.integrity === true,
+    verbose: opts.verboseConfig === true
+  });
+  console.log(formatUnifiedHealth(report));
+  if (report.warnings.some((w) => w.severity === "error")) process.exitCode = 1;
+}
+async function cmdTool(name, opts) {
+  const projectPath = opts.dir ? requireDir(opts.dir) : process.cwd();
+  const { PUBLIC_TOOL_DESCRIPTORS } = await import("./tool-registry-BPEJNSZG.js");
+  const { validateToolArguments } = await import("./tool-validation-Q57YMMBX.js");
+  const { createToolHandlers } = await import("./tool-handlers-OJDC35DI.js");
+  const descriptor = PUBLIC_TOOL_DESCRIPTORS.find((tool) => tool.name === name);
+  if (!descriptor) throw new Error(`unknown public tool ${name}; expected: ${PUBLIC_TOOL_DESCRIPTORS.map((tool) => tool.name).join(", ")}`);
+  let args = {};
+  try {
+    args = opts.args ? JSON.parse(opts.args) : {};
+  } catch {
+    throw new Error("--args must be a JSON object");
+  }
+  if (!args || Array.isArray(args) || typeof args !== "object") throw new Error("--args must be a JSON object");
+  const validated = validateToolArguments(descriptor, args);
+  if (descriptor.requiresIndex) {
+    const validatedArgs = validated;
+    const mode = typeof validatedArgs.mode === "string" ? validatedArgs.mode : void 0;
+    const indexFree = mode !== void 0 && (descriptor.indexFreeModes ?? []).includes(mode);
+    if (!indexFree) {
+      const { BrainDatabase: BrainDatabase2 } = await import("./database-76RP44JG.js");
+      try {
+        await BrainDatabase2.getRawInstance(getProjectId(projectPath), { readonly: true });
+      } catch {
+        throw new Error(`No index found for ${projectPath}. Run: bb index "${projectPath}" (or restart bb mcp after indexing).`);
+      }
+    }
+  }
+  const handler = createToolHandlers()[name];
+  const result = await handler(validated, { projectPath, projectId: getProjectId(projectPath) });
+  console.log(result.content.map((item) => item.text).join("\n"));
+  if (result.isError) process.exitCode = 1;
+}
+async function runCli(argv) {
+  const program = new Command();
+  program.name("bb").description("Backbencher Brain \u2014 evidence is the answer \xB7 code intelligence for 50 languages").version(BACKBENCHER_BRAIN_VERSION, "-v, --version", "output the version number").option("--verbose", "show diagnostics (debug logs, per-file worker/WASM lines)").option("--quiet", "suppress informational output (warnings/errors only)").hook("preAction", (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.verbose) {
+      process.env.BB_LOG_LEVEL = "debug";
+      setLogLevel(1 /* DEBUG */);
+    } else if (opts.quiet) {
+      process.env.BB_LOG_LEVEL = "warn";
+      setLogLevel(3 /* WARN */);
+    }
+  });
+  program.showSuggestionAfterError(true);
+  program.showHelpAfterError("(run 'bb --help' for a list of commands)");
+  program.command("help").description("display help for a command, or list all commands").argument("[command...]", "command to describe; include a subcommand for `bb help <cmd> <sub>` (omit for the command list)").action((commandArg) => {
+    const parts = (Array.isArray(commandArg) ? commandArg : [commandArg]).filter(Boolean);
+    const commandName = parts[0];
+    if (!commandName) {
+      program.outputHelp();
+      return;
+    }
+    const target = program.commands.find((c) => c.name() === commandName);
+    if (!target) {
+      const known = program.commands.map((c) => c.name()).sort();
+      const near = known.filter((n) => n.startsWith(commandName.slice(0, 2)));
+      console.error(`bb help: unknown command "${commandName}" \u2014 no such command.`);
+      if (near.length) console.error(`did you mean: ${near.join(", ")}?`);
+      console.error(`known commands: ${known.join(", ")}`);
+      process.exitCode = 1;
+      return;
+    }
+    let cmd = target;
+    for (const part of parts.slice(1)) {
+      const next = cmd.commands.find((c) => c.name() === part);
+      if (!next) {
+        const subs = cmd.commands.map((c) => c.name()).sort();
+        console.error(`bb help: unknown subcommand "${part}" of "${cmd.name()}" \u2014 no such subcommand.`);
+        if (subs.length) console.error(`its subcommands: ${subs.join(", ")}`);
+        process.exitCode = 1;
+        return;
+      }
+      cmd = next;
+    }
+    cmd.outputHelp();
+  });
+  program.command("tool").description("run one of the public tools with JSON arguments").argument("<name>", "public tool name, e.g. bb_search or bb_doc").argument("[unexpected...]", "rejected: tool arguments are passed with --args '<json>' so a stray positional is an error, not a silent no-op").option("--dir <dir>", "project directory (default: cwd)").option("--args <json>", "tool arguments as a JSON object", "{}").action(async (name, unexpected, opts) => {
+    if (Array.isArray(unexpected) && unexpected.length > 0) {
+      console.error(`\u2717 unexpected argument(s): ${unexpected.map((a) => JSON.stringify(a)).join(" ")}`);
+      console.error(`  Tool arguments are a JSON object: bb tool ${name} --args '{"query":"..."}'`);
+      process.exitCode = 1;
+      return;
+    }
+    await cmdTool(name, opts);
+  });
+  program.command("index").description("index a project (default: current directory)").argument("[dir]", "project directory (default: current directory)").option("--force", "wipe the existing index and rebuild").option("--no-setup", "skip the first-run embedding setup prompt").option("--skip-post-processing", "parse + store only; SKIP relationship resolution/enrichment/gravity/taint/health (derived data goes stale until: bb index --post)").option("--post", "re-run relationship/enrichment/gravity/taint/health phases only \u2014 no re-parse (remediation for stale derived data after --changed/--resume/agent edits)").option(
+    "--file <path>",
+    "reindex a single file's symbols + relationships, relative to <dir> or absolute and must be inside the project (runs a scoped derived-data pass for that file; refuses a missing/outside path)"
+  ).option("--changed", "reindex only files changed since the last index (runs the bounded derived-data pass for touched files \u2014 relationships stay current)").option("--resume", "continue from an interrupted run's checkpoint (incremental: only missing/changed files; runs the bounded derived-data pass)").option("--import <db>", "adopt an existing brain.db file (re-home a moved project's index)").option(
+    "--exclude <globs>",
+    "skip files matching comma-separated globs during discovery (repeatable); NON-DESTRUCTIVE: files already indexed by an earlier run keep their rows",
+    collectList,
+    []
+  ).option("--concurrency <n>", "worker count for this run (1-64; default max(2, min(cpus-1, 12)))").addHelpText("after", `
+Examples:
+  $ bb index                 # index the current directory
+  $ bb index ../my-project   # index another directory
+  $ bb index --changed       # reindex only changed files
+  $ bb index --resume        # continue an interrupted run from its checkpoint
+  $ bb index --file src/a.ts # reindex a single file
+  $ bb index --post          # re-run derived phases only (no re-parse)
+  $ bb index --force         # wipe and rebuild in place
+  $ bb index import --db <path>  # adopt an existing DB for a moved project
+
+Interrupted a run? Re-run with --resume; it re-parses only what is missing or
+changed. Nothing to do? --changed costs seconds where a full run costs minutes.
+Indexing far slower than expected? Run \`bb status\` for per-phase timings and
+\`bb doctor\` to check the worker pool.
+
+Full reference: man bb, or docs/indexing/ in the repository.
+`).action(async (dir, opts) => {
+    await cmdIndex(dir, { ...opts, noSetup: opts.setup === false });
+  });
+  const setupCmd = program.command("setup").description("embedding provider setup (API key, model)");
+  setupCmd.action(async () => {
+    const { runSetupWizard } = await import("./setup-wizard-G5YYR5T6.js");
+    if (!process.stdin.isTTY) {
+      console.error("\u2717 bb setup requires an interactive terminal.");
+      process.exit(1);
+    }
+    await runSetupWizard();
+  });
+  setupCmd.command("show").description("show the embedding configuration (key as fingerprint only)").action(async () => {
+    const { describeEmbeddingConfig, renderSetupShow } = await import("./setup-show-NT5ZHYNE.js");
+    const state = describeEmbeddingConfig();
+    console.log(renderSetupShow(state));
+    if (!state.configured) process.exitCode = 1;
+  });
+  program.command("doctor").description("diagnose embedding setup and index consistency (read-only)").option("--dir <dir>", "project directory (default: cwd)").option("--fix", "repair permission problems (0600 only; this IS the explicit apply \u2014 without it doctor is read-only)").action(async (opts) => {
+    const { runDoctorChecks, renderDoctorReport, applyDoctorFixes, renderFixPlan } = await import("./doctor-ANGETYMN.js");
+    const cwd = opts.dir ? requireDir(opts.dir) : process.cwd();
+    if (opts.fix) {
+      const { plan, applied } = applyDoctorFixes({ cwd, apply: true });
+      console.log(renderFixPlan(plan, applied));
+      if (plan.refusals.length > 0) process.exitCode = 1;
+      return;
+    }
+    const report = runDoctorChecks({ cwd, projectId: getProjectId(cwd) });
+    console.log(renderDoctorReport(report));
+    if (!report.healthy) process.exitCode = 1;
+  });
+  async function cmdUpgrade(opts) {
+    const { BACKBENCHER_BRAIN_VERSION: current, PKG_NAME } = await import("./version-ABP2TUL2.js");
+    const range = opts.to ?? "latest";
+    const spec = `${PKG_NAME}@${range}`;
+    console.log(`bb ${current}`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2e4);
+    let latest = null;
+    let registryError = null;
+    try {
+      const encoded = encodeURIComponent(range);
+      const isDistTag = /^[a-z][a-z0-9._-]*$/i.test(range) && !/^\d/.test(range);
+      const encodedName = encodeURIComponent(PKG_NAME);
+      const url = isDistTag ? `https://registry.npmjs.org/${encodedName}/${encoded}` : `https://registry.npmjs.org/${encodedName}`;
+      const res = await fetch(url, {
+        signal: controller.signal,
+        headers: { accept: "application/json" }
+      });
+      if (!res.ok) {
+        registryError = `registry returned HTTP ${res.status}`;
+      } else {
+        const body = await res.json();
+        if (isDistTag) {
+          latest = typeof body.version === "string" ? body.version : null;
+        } else {
+          const exact = body.versions?.[range];
+          if (exact) {
+            latest = range;
+          } else {
+            const tag = body["dist-tags"]?.latest;
+            latest = typeof tag === "string" ? tag : null;
+          }
+        }
+        if (!latest) registryError = "registry response had no version field";
+      }
+    } catch (e) {
+      registryError = e?.name === "AbortError" ? "registry request timed out after 20s" : e?.message ?? String(e);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!latest) {
+      console.log(`could not check for updates: ${registryError}`);
+      console.log(`compare manually:  npm view ${spec} version`);
+      console.log(`update with:      npm install -g ${spec}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (latest === current) {
+      console.log(`\u2713 up to date (latest published is ${latest})`);
+      return;
+    }
+    console.log(`update available: ${current} -> ${latest}`);
+    console.log(`update with:      npm install -g ${spec}`);
+    if (!opts.check) {
+      console.log(`
+then re-index so the new version's analysis applies:`);
+      console.log(`  bb index --changed`);
+    }
+  }
+  program.command("upgrade").description("check for a newer bb and report exactly how to install it").option("--check", "only report whether a newer version exists; change nothing").option("--to <dist-tag-or-range>", "npm dist-tag or version range to compare against (default: latest)").addHelpText(
+    "after",
+    `
+bb is installed with \`npm install -g @backbencher/brain\`, so npm owns the
+install and bb does not replace its own files. This command reports the installed
+version, the newest published version, and the command to run \u2014 it never mutates
+an install behind npm's back.
+
+  $ bb upgrade --check    # is there a newer version? (no network writes)
+  $ bb upgrade            # same report, plus the exact command to run
+
+After upgrading, re-index:  $ bb index --changed
+`
+  ).action(async (opts) => {
+    await cmdUpgrade(opts);
+  });
+  program.command("stats").description("query index counts anytime: files/symbols/relationships/embeddings (default: cwd)").argument("[dir]", "project directory (default: current directory)").option("--json", "machine-readable JSON output (stable keys for scripts)").action(async (dir, opts) => {
+    await cmdStats(dir, opts);
+  });
+  program.command("status").description("show in-flight/last-run index state and per-phase timings (default: cwd)").argument("[dir]", "project directory (default: current directory)").option("--json", "machine-readable JSON output (stable keys for scripts)").action(async (dir, opts) => {
+    await cmdStatus(dir, opts);
+  });
+  program.command("projects").description("list every indexed project: DB path, size, counts, last index (default: all projects)").option("--sort <field>", "sort by name|size|time", "name").option("--remove <id>", "remove one indexed project by id (reclaims its DB + embeddings)").option("--force", "remove even if that project is currently being indexed").option("--json", "machine-readable JSON output for the project list (stable keys for scripts)").addHelpText("after", `
+Examples:
+  $ bb projects                # list all indexed projects with DB path + size
+  $ bb projects --sort size    # biggest indexes first
+  $ bb projects --remove 1a2b3c4d   # reclaim that project's index space
+`).action(async (opts) => {
+    await cmdProjects(opts);
+  });
+  program.command("search").description("search the index (modes: symbols [default], content, symbol, file \u2014 parity with the MCP bb_search tool)").argument("[query]", "query text; in file mode, the file path to print (omit when --symbol-name or --file-path is given)").option("--mode <mode>", "retrieval mode: symbols (default), content, symbol, or file").option("--file-path <path>", "file target for --mode file (overrides the positional query)").option("--symbol-name <name>", "exact symbol name for --mode symbol (overrides the positional query)").option("--dir <dir>", "project directory (default: cwd)").option("--limit <n>", "max results", "15").option("--language <lang>", "filter by language").option("--no-auto-refresh", "answer from the existing index with the staleness footer instead of auto-refreshing stale files within budget").addHelpText("after", `
+Examples:
+  $ bb search handleRequest                 # symbol listing (default)
+  $ bb search --mode content "findUser("    # content matches with snippets
+  $ bb search --mode symbol --symbol-name handleRequest
+  $ bb search --mode file src/app.ts        # print an indexed file's content
+  $ bb search --no-auto-refresh query      # never auto-refresh on read
+`).action(async (query, opts) => {
+    if (!query && !opts.symbolName && !opts.filePath) {
+      console.error(
+        "bb search: nothing to search for. Pass a query, or --symbol-name <name>, or --file-path <path>."
+      );
+      process.exitCode = 1;
+      return;
+    }
+    await cmdSearch(query, { ...opts, noAutoRefresh: opts.autoRefresh === false, limit: parseInt(opts.limit, 10) });
+  });
+  program.command("health").description("index health and freshness").argument("[dir]", "project directory (default: cwd)").option("--refresh", "reindex the project before reporting").option("--force", "force a full in-place reindex (implies --refresh)").option("--no-wait", "do not wait for the refresh to finish").option("--complete", "check freshness for all files (not just a sample)").option("--integrity", "run the 12-point index integrity check").option("--sample-size <n>", "freshness sample size (default: 200)", "200").option("--verbose-config", "show effective embedding config + per-field source (M40.A8)").action(async (dir, opts) => {
+    await cmdHealth(dir, { ...opts, sampleSize: parseInt(opts.sampleSize, 10) });
+  });
+  program.command("onboard").description("write the bb tools guidance section into <dir>/AGENTS.md (generated from the tool registry)").argument("[dir]", "project directory (default: current directory)").option("--check", "report drift/ghost tool names without writing (exit 1 when not current)").option("--print", "print the generated section to stdout without writing").option("--file <path>", "guide file to write (default: <dir>/AGENTS.md)").addHelpText("after", `
+Examples:
+  $ bb onboard                # write/refresh AGENTS.md in the current project
+  $ bb onboard ../my-project  # same for another directory
+  $ bb onboard --check        # CI: fail when the guidance drifted or names a ghost tool
+  $ bb onboard --print        # show the generated section
+`).action(async (dir, opts) => {
+    const { onboard, renderOnboardResult } = await import("./onboard-DIQZV2NW.js");
+    const abs = dir ? requireDir(dir) : process.cwd();
+    const result = onboard(abs, { check: opts.check === true, print: opts.print === true, file: opts.file });
+    console.log(renderOnboardResult(result));
+    if (opts.check === true && result.changed) process.exitCode = 1;
+  });
+  program.command("mcp").description("start the MCP server over stdio (for Claude Code, Cursor, VS Code\u2026)").option("--dir <dir>", "default project directory (default: cwd)").action(async (opts) => {
+    const { startMcpServer } = await import("./mcp/server.js");
+    await startMcpServer(opts.dir ? requireDir(opts.dir) : process.cwd());
+  });
+  program.command("version").description("print the bb version").action(() => {
+    console.log(BACKBENCHER_BRAIN_VERSION);
+  });
+  await program.parseAsync(argv, { from: "user" });
+}
+var isDirectRun = (() => {
+  const m = import.meta;
+  if (typeof m.main === "boolean") return m.main;
+  try {
+    const entry = process.argv[1] ? path.resolve(process.argv[1]) : null;
+    if (!entry) return false;
+    const self = fileURLToPath(m.url ?? import.meta.url);
+    const real = (p) => {
+      try {
+        return realpathSync.native(p);
+      } catch {
+        return p;
+      }
+    };
+    return real(entry) === real(self);
+  } catch {
+    return false;
+  }
+})();
+if (isDirectRun) {
+  try {
+    await runCli(process.argv.slice(2));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`error: ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+export {
+  runCli
+};