token-goat 2.9.28 → 2.9.30

package/dist/token-goat-chunk-CZ3LUXYZ.mjs

@@ -0,0 +1,4115 @@
+import { createRequire as __cjsRequire } from 'node:module';
+const require = __cjsRequire(import.meta.url);
+import {
+  formatSqliteQueryTable,
+  formatSqliteSchema,
+  formatSqliteTables,
+  getSqliteSchema,
+  getSqliteTables,
+  runReadOnlySqliteQuery
+} from "./token-goat-chunk-ZCDTCVIS.mjs";
+import {
+  DELETED_TAG,
+  DIDYOUMEAN_LIMIT,
+  FIND_SCAN_LIMIT,
+  FirstRows,
+  REF_BLIND_DEF_PROBE_LIMIT,
+  UNBOUNDED_QUERY_LIMIT,
+  WHOLE_FILE_NOTE_SYMBOL,
+  buildContextWindow,
+  compareBinary,
+  confinedProjectRoot,
+  confinementRefusal,
+  didYouMean,
+  emit,
+  emitErr,
+  emitGuarded,
+  extractExportNames,
+  extractImports,
+  fileConfinementRefusal,
+  fileExists,
+  fileIsGone,
+  filterSimilarHeadings,
+  findSpecSeparator,
+  findStructuredKeyPath,
+  firstBodyLine,
+  forEachSymbol,
+  formatAmbiguity,
+  formatBareNameSpecError,
+  formatStatsSuffix,
+  getNote,
+  guardJsonRows,
+  guardText,
+  hasRealDocstring,
+  healStaleIndex,
+  healStaleResultFiles,
+  importsExtensionFor,
+  indexFileSyncPinned,
+  indexFreshness,
+  isNoteStale,
+  isRefIndexedFile,
+  isValidUtf8,
+  largestFileSize,
+  listNotes,
+  nearNamesSkippedNote,
+  nearSymbolNames,
+  noSymbolsMessage,
+  parseCrossFileMultiSpec,
+  parseMultiFileSpec,
+  parseReadSpec,
+  previewLines,
+  projectStructuredFiles,
+  rankSimilarNames,
+  readFileBytes,
+  readFileText,
+  recordReadStat,
+  recordStaleServed,
+  refBlindKindNotice,
+  refBlindKindPartialNote,
+  refBlindKindVerdict,
+  refBlindLanguageNotice,
+  renderContextWindow,
+  resolveAgainstProjectRoot,
+  resolveBody,
+  resolveCallers,
+  resolveProjectConfinement,
+  resolveQualifiedSpec,
+  resolveQualifiedSpecDef,
+  resolveSpecPath,
+  resolveSymbolSpec,
+  resolveSymbolSpecOrEmitError,
+  sinkGoneRows,
+  specScopeRoot,
+  staleWarning,
+  stripHtmlIdSpelling,
+  sumFileSizes,
+  symbolsById,
+  trimBlankLines,
+  truncationFooter,
+  truncationNotice,
+  typedRefsForDef,
+  unknownSymbolSuggestion,
+  warnIfFilesStale
+} from "./token-goat-chunk-PU7V3FD6.mjs";
+import {
+  parseJsonOrJsonc
+} from "./token-goat-chunk-XKI4SEMX.mjs";
+import {
+  MODEL_DOWNLOAD_HOST,
+  RUNTIME_DOWNLOAD_HOST,
+  activeDownloadCooldown,
+  isExplicitDownload,
+  lastDownloadFailure,
+  withExplicitDownload
+} from "./token-goat-chunk-SMVRN2HU.mjs";
+import {
+  commentSyntaxFor
+} from "./token-goat-chunk-5RG5SBL6.mjs";
+import {
+  deliveredOutputBytes
+} from "./token-goat-chunk-54K3EUV3.mjs";
+import {
+  NOTEBOOK_CELL_LINES_SUFFIX,
+  emptyIndexMessage,
+  formatSymbolLocation,
+  getEmbeddingCoverage,
+  isIgnoredIndexPath,
+  isIndexEmptyForProject,
+  isVirtualIndexedPath,
+  searchEvidenceSemantically,
+  virtualIndexedScopeNote,
+  walkProject
+} from "./token-goat-chunk-FBNQNSJK.mjs";
+import {
+  enqueueDirtyPathSafe
+} from "./token-goat-chunk-H2PHHGM5.mjs";
+import {
+  ensureWorkerAlive,
+  fetchBypassesProxy,
+  nodeFetchHonoursEnvProxy,
+  proxyConfigured
+} from "./token-goat-chunk-5KDMCMF2.mjs";
+import {
+  MAX_OVER_FETCH,
+  NATIVE_RUNTIME_INSTALL,
+  ORT_WEB_WASM,
+  OVER_FETCH_FACTOR,
+  RUNTIME_UNAVAILABLE_ADVICE,
+  activeRuntime,
+  checkEmbeddingPreflight,
+  eachUnfencedLine,
+  embeddingBackendLoadError,
+  findContainingSection,
+  isAvailable,
+  listSections,
+  modelDir,
+  modelFilesPresent,
+  readSection,
+  searchSemantic,
+  wasmBinaryPresent
+} from "./token-goat-chunk-RHXKCZX3.mjs";
+import {
+  ATX_CLASS_BREAK_RE,
+  matchAtxHeading
+} from "./token-goat-chunk-EVMZJ27Z.mjs";
+import {
+  DEFAULT_QUERY_LIMIT,
+  countRefs,
+  countSymbols,
+  queryRefCounts,
+  queryRefs,
+  querySymbols,
+  searchSymbolsFts
+} from "./token-goat-chunk-HYBFA5X3.mjs";
+import {
+  isBlobStale,
+  loadBlob,
+  storeBlob
+} from "./token-goat-chunk-ARDNEC2U.mjs";
+import {
+  BYTES_PER_TOKEN,
+  getGlobalDb,
+  recordStat,
+  savedTokensFromBytes,
+  withTelemetryWriteDb
+} from "./token-goat-chunk-3Z5S4KGM.mjs";
+import {
+  detectLanguage,
+  detectLanguageOfFile,
+  getDb
+} from "./token-goat-chunk-VL3YIFHZ.mjs";
+import {
+  redactSecrets
+} from "./token-goat-chunk-4FVIAHSI.mjs";
+import {
+  findProject,
+  getDisplayRoot,
+  getProjectConfigInfo,
+  loadConfig,
+  parse,
+  projectHash,
+  resolveConfigKeyLayer,
+  resolveProjectRoot,
+  shortFingerprint
+} from "./token-goat-chunk-7IN2MKDS.mjs";
+import {
+  MAX_ZIP_OUTPUT_BYTES,
+  ZipInputTooLargeError,
+  ZipOutputTooLargeError,
+  unzipBounded
+} from "./token-goat-chunk-XTQAOTSO.mjs";
+import {
+  createLazyModuleLoader
+} from "./token-goat-chunk-AH6QILZM.mjs";
+import {
+  compileGrepMatcher,
+  countNoun,
+  escapeRegExp,
+  excludeTestsHiddenNote,
+  extractErrorMessage,
+  filtersFilteredToEmptyNotice,
+  grepFilteredToEmptyNotice,
+  isTestFile,
+  requireNonNegativeStrictInt,
+  runGit,
+  stripBom
+} from "./token-goat-chunk-GOLEOXZP.mjs";
+import {
+  foldPath
+} from "./token-goat-chunk-AM5V6GSX.mjs";
+import {
+  displaySafeJson,
+  displaySafeText,
+  normalizePath,
+  resolveIndexPath,
+  toDisplayPath
+} from "./token-goat-chunk-FNFBKLRD.mjs";
+import {
+  SKELETON_SYMBOL_CAP,
+  globalDbPath
+} from "./token-goat-chunk-VES7EL7O.mjs";
+import {
+  init_define_import_meta_env
+} from "./token-goat-chunk-A37V4PBF.mjs";
+
+// src/embed_preflight.ts
+init_define_import_meta_env();
+var MODEL_MB = 35;
+var WARM_COMMAND = "token-goat semantic --preflight --warm";
+function pendingDownloadHosts() {
+  const hosts = [];
+  if (!modelFilesPresent()) hosts.push(MODEL_DOWNLOAD_HOST);
+  if (activeRuntime() === "onnxruntime-web" && !wasmBinaryPresent()) hosts.push(RUNTIME_DOWNLOAD_HOST);
+  return hosts;
+}
+function modelDownloadHeld(now = Date.now()) {
+  const hosts = pendingDownloadHosts();
+  if (hosts.length === 0) return false;
+  if (loadConfig().network?.offline === true) return true;
+  return hosts.some((host) => activeDownloadCooldown(host, now) !== null);
+}
+function foregroundDownloadDeferred(now = Date.now(), env = process.env, nodeVersion = process.versions.node) {
+  if (modelDownloadHeld(now)) return true;
+  return !isExplicitDownload() && fetchBypassesProxy(env, nodeVersion) && pendingDownloadHosts().length > 0;
+}
+function downloadAdvice(env = process.env, nodeVersion = process.versions.node) {
+  return `${proxyAdvice(env, nodeVersion)}, or copy the model files into ${modelDir()}. Then run \`${WARM_COMMAND}\` to download it now.`;
+}
+function runtimeDownloadAdvice(env = process.env, nodeVersion = process.versions.node) {
+  return `${proxyAdvice(env, nodeVersion)}, or ${NATIVE_RUNTIME_INSTALL}. Then run \`${WARM_COMMAND}\` to download it now.`;
+}
+function proxyAdvice(env, nodeVersion) {
+  const proxied = proxyConfigured(env);
+  const honoured = nodeFetchHonoursEnvProxy(nodeVersion);
+  if (proxied && !honoured) return `This machine sets a proxy, but Node ${nodeVersion} cannot send fetch through it: upgrade to Node 22.21+ or 24+`;
+  if (proxied && env["NODE_USE_ENV_PROXY"] === "0") return "NODE_USE_ENV_PROXY=0 sends token-goat's downloads around the proxy in HTTPS_PROXY. If this machine reaches the internet only through that proxy, remove it";
+  if (proxied) return `Check that the proxy in HTTPS_PROXY lets ${MODEL_DOWNLOAD_HOST} and ${RUNTIME_DOWNLOAD_HOST} through. If this machine reaches them without it, set NODE_USE_ENV_PROXY=0 and token-goat's downloads go around the proxy`;
+  if (!honoured) return "If this machine reaches the internet through a proxy, set HTTPS_PROXY to it and upgrade to Node 22.21+ or 24+, the first versions that can use it";
+  return "If this machine reaches the internet through a proxy, set HTTPS_PROXY to it";
+}
+function explainModelDownload(result, now = Date.now()) {
+  if (result.modelWarmed) return result.modelFilesPresent ? result : { ...result, modelFilesPresent: true };
+  if (result.status !== "ready" && result.status !== "no_embeddings" && result.status !== "load_error") return result;
+  const pending = pendingDownloadHosts();
+  if (pending.length === 0) return result;
+  const modelMissing = pending.includes(MODEL_DOWNLOAD_HOST);
+  const rebuild = (status, available, message, suggestion, error) => {
+    const { suggestion: _s, actionRequired: _a, error: _e, ...rest } = result;
+    return {
+      ...rest,
+      status,
+      available,
+      message,
+      summary: message,
+      modelFilesPresent: !modelMissing,
+      ...suggestion !== void 0 ? { suggestion, actionRequired: suggestion } : {},
+      ...error !== void 0 ? { error } : {}
+    };
+  };
+  let failure = null;
+  for (const host of pending) {
+    const record = lastDownloadFailure(host);
+    if (record !== null && (failure === null || record.at > failure.at)) failure = { host, at: record.at, message: record.message };
+  }
+  if (failure !== null) {
+    const cooldown = activeDownloadCooldown(failure.host, now);
+    const when = cooldown !== null ? `It is tried again automatically after ${new Date(cooldown.retryAt).toISOString()}.` : "It is tried again automatically the next time a file is embedded.";
+    const runtime = failure.host === RUNTIME_DOWNLOAD_HOST;
+    const what = runtime ? `The WebAssembly runtime the embedding model runs on (onnxruntime-web, from ${RUNTIME_DOWNLOAD_HOST}) is not downloaded yet` : "The embedding model is not downloaded yet";
+    const message = `${what}. The last try, at ${new Date(failure.at).toISOString()}, failed: ${failure.message}. ${when}`;
+    return rebuild(runtime ? "missing_runtime" : "missing_model_files", false, message, runtime ? runtimeDownloadAdvice() : downloadAdvice(), message);
+  }
+  if (result.status === "load_error" || !modelMissing) return result;
+  if (result.status === "no_embeddings") {
+    const message = `The embedding model (about ${MODEL_MB} MB, once) is not downloaded yet. It downloads by itself in the background, and this project's ${result.indexedFiles} indexed file(s) are embedded after it.`;
+    return rebuild("missing_model_files", false, message, `Nothing to do. To download it now instead, run \`${WARM_COMMAND}\`.`, void 0);
+  }
+  return rebuild("ready", true, `Semantic search is ready. The embedding model (about ${MODEL_MB} MB) is not downloaded yet; it is fetched on first use.`, void 0, void 0);
+}
+async function checkSemanticReadiness(options) {
+  return explainModelDownload(await checkEmbeddingPreflight(options));
+}
+function offlineEmbedNotice(fileCount, rootDir) {
+  const cfg = loadConfig(rootDir);
+  if (!cfg.network.offline) return null;
+  const state = resolveConfigKeyLayer("network.offline", cfg.network.offline, cfg, getProjectConfigInfo(rootDir));
+  const holder = state.layer === "env" || state.layer === "env-invalid" ? `${state.envVar} is set in your environment` : state.layer === "project" ? `${displaySafeText(state.path)} sets network.offline` : "network.offline is on in config.toml";
+  return `token-goat: index: ${fileCount} not embedded: the embedding model is not downloaded and ${holder}, so nothing will download it. symbol, read, outline and section work now; semantic falls back to keyword search. To embed them, unset it so the worker can download the model, or copy the pinned model files into ${modelDir()}; then run \`token-goat index\` again.`;
+}
+
+// src/read_symbol.ts
+init_define_import_meta_env();
+var SYMBOL_PREVIEW_LINES = 5;
+var STALE_TAG = "\u26A0 STALE: file changed on disk and could not be reindexed";
+var EMPTY_PATH_SET = /* @__PURE__ */ new Set();
+var IMPORT_BIND_BODY_RE = /^\s*(?:const|let|var)\s*\{[^}]*\}\s*=\s*(?:await\s+)?(?:import|require)\s*\(/;
+function stableSortImportBindsLast(rows) {
+  const isBind = (r) => typeof r.body === "string" && IMPORT_BIND_BODY_RE.test(r.body) ? 1 : 0;
+  return [...rows].sort((a, b) => isBind(a) - isBind(b));
+}
+function runSymbol(opts) {
+  if (opts.limit !== void 0 && opts.limit <= 0) {
+    return { text: `--limit must be a positive number, got: ${opts.limit}`, code: 1 };
+  }
+  if (opts.name !== void 0 && opts.grep !== void 0) {
+    return {
+      text: "symbol: --grep cannot be combined with a name; drop the name to search by pattern, or drop --grep to search by exact name",
+      code: 1
+    };
+  }
+  if (opts.name === void 0 && opts.grep === void 0) {
+    return { text: "symbol requires a name or --grep <pattern>", code: 1 };
+  }
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  const excludeTests = opts.excludeTests === true;
+  const excludeVendored = opts.excludeVendored === true;
+  const { root: confinedRoot, denial: projectDenial } = resolveProjectConfinement(opts.projectRoot);
+  if (projectDenial !== null) return { text: projectDenial, code: 1 };
+  if (confinedRoot !== null && opts.file !== void 0) {
+    const fileDenial = confinementRefusal("--file", resolveSpecPath(opts.file, opts.projectRoot ?? process.cwd()), confinedRoot);
+    if (fileDenial !== null) return { text: fileDenial, code: 1 };
+  }
+  const queryOpts = {};
+  if (opts.file !== void 0) {
+    queryOpts.filePath = resolveSpecPath(opts.file, opts.projectRoot ?? process.cwd());
+    healStaleIndex(queryOpts.filePath);
+  }
+  if (opts.name !== void 0) queryOpts.name = queryOpts.filePath !== void 0 ? stripHtmlIdSpelling(opts.name, queryOpts.filePath) : opts.name;
+  if (opts.kind !== void 0) queryOpts.kind = opts.kind;
+  const anyClientFilter = matchesGrep !== void 0 || excludeTests || excludeVendored;
+  const effectiveLimit = opts.limit ?? DEFAULT_QUERY_LIMIT;
+  if (!anyClientFilter && opts.limit !== void 0) {
+    queryOpts.limit = opts.limit;
+  }
+  if (opts.file === void 0 && opts.projectRoot !== void 0) queryOpts.rootDir = opts.projectRoot;
+  if (opts.file === void 0 && queryOpts.rootDir === void 0 && confinedRoot !== null) queryOpts.rootDir = confinedRoot;
+  const preferRoot = opts.file === void 0 && queryOpts.rootDir === void 0 ? resolveProjectRoot({ project: process.cwd() }) : void 0;
+  const rowKept = (s) => (matchesGrep === void 0 || matchesGrep(s.name)) && !(excludeTests && isTestFile(s.filePath)) && !(excludeVendored && isIgnoredIndexPath(s.filePath));
+  const runSweep = () => {
+    const found = { kept: [], keptCount: 0, scanned: 0, hiddenByExcludeTests: 0, files: /* @__PURE__ */ new Set(), mineCount: 0, mineKept: 0 };
+    const admit = (s) => {
+      found.scanned++;
+      found.files.add(s.filePath);
+      const nameKept = matchesGrep === void 0 || matchesGrep(s.name);
+      if (rowKept(s)) {
+        found.keptCount++;
+        return true;
+      }
+      if (excludeTests && nameKept && isTestFile(s.filePath)) found.hiddenByExcludeTests++;
+      return false;
+    };
+    if (anyClientFilter) {
+      const mine = new FirstRows(effectiveLimit);
+      if (preferRoot !== void 0) {
+        forEachSymbol({ ...queryOpts, rootDir: preferRoot }, (s) => {
+          if (rowKept(s)) {
+            found.mineKept++;
+            mine.offer(s);
+          }
+        });
+      }
+      const mineRows = mine.rows();
+      const mineIds = new Set(mineRows.map((s) => s.id));
+      const first = new FirstRows(effectiveLimit + mineRows.length);
+      forEachSymbol(queryOpts, (s) => {
+        if (admit(s)) first.offer(s);
+      });
+      const rest = first.rows().filter((s) => !mineIds.has(s.id));
+      found.mineCount = mineRows.length;
+      found.kept = symbolsById([...mineRows, ...rest].slice(0, effectiveLimit).map((s) => s.id));
+    } else if (preferRoot !== void 0) {
+      const mineRows = querySymbols({ ...queryOpts, rootDir: preferRoot, limit: effectiveLimit });
+      const rowKey = (r) => [r.filePath, r.lineStart, r.name].join("|");
+      const mineKeys = new Set(mineRows.map(rowKey));
+      const all = querySymbols({ ...queryOpts, limit: effectiveLimit + mineRows.length });
+      for (const row of all) admit(row);
+      found.kept = [...mineRows, ...all.filter((r) => !mineKeys.has(rowKey(r)))].slice(0, effectiveLimit);
+      found.mineCount = mineRows.length;
+    } else {
+      for (const row of querySymbols(queryOpts)) if (admit(row) && found.kept.length < effectiveLimit) found.kept.push(row);
+    }
+    return found;
+  };
+  let sweep = runSweep();
+  let stillStale = EMPTY_PATH_SET;
+  if (opts.file === void 0) {
+    const heal = healStaleResultFiles([...sweep.files]);
+    stillStale = heal.stillStale;
+    if (heal.healed) sweep = runSweep();
+  }
+  const preFilterCount = sweep.scanned;
+  const unordered = sweep.kept.slice(0, effectiveLimit);
+  const orderGroup = (rows) => opts.name === void 0 ? rows : stableSortImportBindsLast(rows);
+  const ordered = [...orderGroup(unordered.slice(0, sweep.mineCount)), ...orderGroup(unordered.slice(sweep.mineCount))];
+  const results = sinkGoneRows(ordered, (s) => s.filePath);
+  if (opts.file === void 0) {
+    if (results.some((s) => stillStale.has(s.filePath))) recordStaleServed("symbol", "stale");
+    if (results.some((s) => fileIsGone(s.filePath))) recordStaleServed("symbol", "deleted");
+  }
+  const hiddenByExcludeTests = sweep.hiddenByExcludeTests;
+  if (excludeTests && sweep.keptCount === 0 && hiddenByExcludeTests > 0) {
+    const label = opts.name ?? opts.grep ?? "*";
+    const notice = `no non-test matches for '${label}' (${excludeTestsHiddenNote(hiddenByExcludeTests)})`;
+    if (opts.json === true) {
+      return { text: displaySafeJson({ items: [], truncated: false, totalCount: 0 }), code: 0 };
+    }
+    return { text: `token-goat: ${notice}`, code: 0 };
+  }
+  if (matchesGrep !== void 0 && sweep.keptCount === 0 && preFilterCount > 0) {
+    if (opts.json === true) {
+      const text2 = displaySafeJson({ items: [], truncated: false, totalCount: 0 });
+      return { text: text2, code: 0 };
+    }
+    return { text: grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "symbol", "symbols"), code: 0 };
+  }
+  if (results.length === 0) {
+    if (opts.json === true) {
+      return { text: displaySafeJson({ items: [], truncated: false, totalCount: 0 }), code: 0 };
+    }
+    let text2 = `No matches for '${opts.name ?? opts.grep ?? "*"}'`;
+    const emptyIndexRoot = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
+    const indexEmpty = isIndexEmptyForProject(globalDbPath(), emptyIndexRoot);
+    if (opts.name !== void 0) {
+      const rootDir = emptyIndexRoot;
+      const exactMatches = querySymbols({ name: opts.name, rootDir, limit: DIDYOUMEAN_LIMIT });
+      if (exactMatches.length > 0) {
+        const total = exactMatches.length < DIDYOUMEAN_LIMIT ? exactMatches.length : countSymbols({ name: opts.name, rootDir });
+        const where = exactMatches.map((s) => `${s.kind} at ${formatSymbolLocation(toDisplayPath(rootDir, s.filePath), s.lineStart)}`).join("; ");
+        const more = total > exactMatches.length ? ` (+${total - exactMatches.length} more)` : "";
+        const flags = [opts.kind !== void 0 ? "--kind" : null, opts.file !== void 0 ? "--file" : null].filter((f) => f !== null);
+        const widen = flags.length > 0 ? `drop ${flags.join("/")} to see it` : "widen the search scope to see it";
+        text2 += `
+'${opts.name}' IS indexed (${where}${more}) -- ${widen}`;
+      } else {
+        const near = nearSymbolNames(opts.name, rootDir);
+        const semanticHint = indexEmpty ? "" : `
+Try: token-goat semantic "${opts.name}"`;
+        if (near.skipped) text2 += `
+${nearNamesSkippedNote()}${semanticHint}`;
+        else text2 += near.candidates.length > 0 ? `
+${didYouMean(near.candidates)}` : semanticHint;
+      }
+      const structuredFiles = projectStructuredFiles(rootDir);
+      const hit = findStructuredKeyPath(opts.name, structuredFiles);
+      if (hit !== null) {
+        const display = toDisplayPath(rootDir, hit.filePath);
+        text2 += `
+'${opts.name}' is a key in ${display} at ${hit.dotPath} -- JSON/YAML keys below the top level are not symbols; read it with: token-goat ${hit.command} ${display} '${hit.dotPath}'`;
+      }
+    }
+    if (indexEmpty) {
+      text2 += `
+${emptyIndexMessage(emptyIndexRoot)}`;
+    }
+    return { text: text2, code: 1 };
+  }
+  const fullSourceBytes = largestFileSize(results.map((s) => s.filePath));
+  const symbolDisplayRoot = getDisplayRoot(opts.projectRoot);
+  const refCounts = opts.stats === true ? queryRefCounts(
+    results.map((s) => s.name),
+    globalDbPath(),
+    resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() })
+  ) : void 0;
+  if (opts.json === true) {
+    const capped = guardJsonRows(results);
+    let trueTotal;
+    let truncatedFlag;
+    if (anyClientFilter) {
+      trueTotal = sweep.keptCount;
+      truncatedFlag = capped.truncated || results.length < sweep.keptCount;
+    } else {
+      trueTotal = countSymbols(queryOpts);
+      truncatedFlag = capped.truncated || trueTotal > results.length;
+    }
+    const items = capped.items.map((s) => ({
+      ...s,
+      filePath: toDisplayPath(symbolDisplayRoot, s.filePath),
+      // Only present when true, so a result set of live files stays byte-identical to what this command has always emitted and only the genuinely-gone rows grow a field.
+      ...fileIsGone(s.filePath) ? { deleted: true } : {},
+      ...stillStale.has(s.filePath) ? { stale: true } : {},
+      ...refCounts !== void 0 ? { refCount: refCounts.get(s.name) ?? 0, hasDoc: hasRealDocstring(s.docstring) } : {}
+    }));
+    const payload = { items, truncated: truncatedFlag, totalCount: trueTotal };
+    if (opts.file !== void 0) recordStaleServed("symbol", indexFreshness(resolveSpecPath(opts.file, opts.projectRoot ?? process.cwd())));
+    const text2 = displaySafeJson(payload);
+    recordReadStat("symbol_lookup", fullSourceBytes, text2, opts.name ?? opts.file ?? opts.grep);
+    return { text: text2, code: 0 };
+  }
+  const blocks = results.map((sym) => {
+    const statsStr = formatStatsSuffix(refCounts, sym);
+    const goneTag = fileIsGone(sym.filePath) ? `  ${DELETED_TAG}` : "";
+    const staleTag = stillStale.has(sym.filePath) ? `  ${STALE_TAG}` : "";
+    const header = `# ${sym.name} (${sym.kind}) \u2014 ${formatSymbolLocation(toDisplayPath(symbolDisplayRoot, sym.filePath), sym.lineStart, sym.lineEnd)}${statsStr}${goneTag}${staleTag}`;
+    const body = resolveBody(sym);
+    const bodyLines = body.split(/\r?\n/);
+    const preview = bodyLines.slice(0, SYMBOL_PREVIEW_LINES).join("\n");
+    const dropped = bodyLines.length - SYMBOL_PREVIEW_LINES;
+    const elided = dropped > 0 ? `
+  ...(${countNoun(dropped, "more line")}; full body: token-goat read "${toDisplayPath(symbolDisplayRoot, sym.filePath)}::${sym.name}")` : "";
+    return preview.trim() !== "" ? `${header}
+${preview}${elided}` : header;
+  });
+  const warning = opts.file !== void 0 ? staleWarning(resolveSpecPath(opts.file, opts.projectRoot ?? process.cwd()), "symbol") : "";
+  const text = guardText(warning + blocks.join("\n\n"), "symbol");
+  recordReadStat("symbol_lookup", fullSourceBytes, text, opts.name ?? opts.file ?? opts.grep);
+  let cachedTotal;
+  const symbolTotal = () => {
+    cachedTotal ??= anyClientFilter ? { count: sweep.keptCount, exact: true } : { count: countSymbols(queryOpts), exact: true };
+    return cachedTotal;
+  };
+  const footer = truncationFooter(results.length, effectiveLimit, symbolTotal, "matches", "--limit");
+  const mineTotal = footer !== "" && preferRoot !== void 0 ? anyClientFilter ? sweep.mineKept : countSymbols({ ...queryOpts, rootDir: preferRoot }) : 0;
+  const someElsewhere = mineTotal > 0 && mineTotal < symbolTotal().count;
+  const mineNote = someElsewhere ? `
+token-goat: ${mineTotal} of the matches are in this project and listed first; pass -p to search only it` : "";
+  return { text: text + footer + mineNote, code: 0 };
+}
+
+// src/read_brief.ts
+init_define_import_meta_env();
+function runBriefCore(opts) {
+  const resolution = resolveSymbolSpec(opts.spec, void 0, opts.projectRoot);
+  if (resolution.kind === "confined") return { text: resolution.message, code: 1 };
+  if (resolution.kind === "ambiguous") {
+    return {
+      // Name the command explicitly: formatAmbiguity defaults to 'read', so brief's retry lines would otherwise tell the user to run `token-goat read`, which answers a different question than the one they asked.
+      text: formatAmbiguity(
+        resolution.symbol,
+        resolution.file,
+        resolution.candidates,
+        opts.projectRoot,
+        "brief"
+      ),
+      code: 1
+    };
+  }
+  if (resolution.kind === "none") {
+    if (findSpecSeparator(opts.spec) === -1) {
+      return { text: formatBareNameSpecError("brief", opts.spec, opts.projectRoot), code: 1 };
+    }
+    if (opts.json !== true) {
+      const rootDir2 = resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() });
+      if (isIndexEmptyForProject(globalDbPath(), rootDir2)) {
+        return { text: `Symbol not found: ${opts.spec}
+${emptyIndexMessage(rootDir2)}`, code: 1 };
+      }
+    }
+    return { text: `Symbol not found: ${opts.spec}`, code: 1 };
+  }
+  const match = resolution.entry;
+  const rootDir = specScopeRoot(opts.spec, resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() })).root;
+  const excludeTests = opts.excludeTests === true;
+  const allCallers = resolveCallers(match.name, void 0, match.filePath, rootDir, true, ...match.kind === "method" ? [match] : []);
+  const testFiltered = excludeTests ? allCallers.filter((c) => !isTestFile(c.file)) : allCallers;
+  const hiddenByExcludeTests = excludeTests ? allCallers.length - testFiltered.length : 0;
+  const preGrepCount = testFiltered.length;
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  const callers = matchesGrep !== void 0 ? testFiltered.filter((c) => matchesGrep(c.caller)) : testFiltered;
+  const hiddenByGrep = matchesGrep !== void 0 ? preGrepCount - callers.length : 0;
+  const totalCallers = callers.length;
+  const section = findContainingSection(match.filePath, match.lineStart, match.lineEnd, readFileText);
+  const limit = opts.limit ?? 20;
+  const shown = callers.slice(0, limit);
+  const truncated = totalCallers > shown.length;
+  const fullSourceBytes = sumFileSizes([match.filePath]);
+  if (opts.json === true) {
+    const callersWithContext = (opts.context ?? 0) > 0 ? shown.map((c) => ({ ...c, contextLines: buildContextWindow(c.file, c.line, opts.context ?? 0) ?? [] })) : shown;
+    const result = {
+      symbol: { ...match, body: resolveBody(match), filePath: toDisplayPath(rootDir, match.filePath) },
+      callers: callersWithContext.map((c) => ({ ...c, file: toDisplayPath(rootDir, c.file) })),
+      totalCallers,
+      truncated,
+      ...hiddenByExcludeTests > 0 ? { hiddenByExcludeTests } : {},
+      ...hiddenByGrep > 0 ? { hiddenByGrep } : {},
+      // Mirrors runRead's json branch: emitting the row verbatim would hand a JSON consumer a deleted file's stale body with no signal it is no longer live.
+      ...fileIsGone(match.filePath) ? { deleted: true } : {},
+      section
+    };
+    const jsonText = displaySafeJson(result);
+    recordStaleServed("brief", indexFreshness(match.filePath));
+    if (opts.suppressStat !== true) recordReadStat("brief_view", fullSourceBytes, jsonText, opts.spec);
+    return { text: jsonText, code: 0 };
+  }
+  const body = resolveBody(match);
+  const bodyLen = match.lineEnd - match.lineStart + 1;
+  const lines = [
+    // This header is token-goat's own line quoting a repo-chosen name, kind and path, so it is escaped. `body` below it is the source the reader asked for and stays byte-for-byte.
+    `# ${displaySafeText(match.name)}  ${displaySafeText(match.kind)}  ${formatSymbolLocation(displaySafeText(toDisplayPath(rootDir, match.filePath)), match.lineStart, match.lineEnd)}`,
+    `# ${countNoun(bodyLen, "line")} (~${Math.ceil(body.length / 4)} tok)`,
+    body,
+    ""
+  ];
+  const warning = staleWarning(match.filePath, "brief");
+  const hiddenNote = excludeTests && hiddenByExcludeTests > 0 ? ` (${excludeTestsHiddenNote(hiddenByExcludeTests)})` : "";
+  if (callers.length === 0 && matchesGrep !== void 0 && preGrepCount > 0) {
+    lines.push(`Callers (0): ${grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "caller", "callers").trim()}`);
+  } else {
+    lines.push(callers.length === 0 && hiddenNote !== "" ? `Callers (0): no non-test callers${hiddenNote}` : `Callers (${totalCallers}):${hiddenNote}`);
+  }
+  for (const c of shown) {
+    const callerDisplayPath = toDisplayPath(rootDir, c.file);
+    lines.push(`  ${c.caller}	${callerDisplayPath}:${c.line}`);
+    const window = buildContextWindow(c.file, c.line, opts.context ?? 0);
+    if (window !== null) lines.push(...renderContextWindow(callerDisplayPath, c.line, window, "", "    "));
+  }
+  if (truncated) {
+    lines.push(`  ...(${totalCallers - shown.length} more elided)`);
+  }
+  if (section !== null) {
+    lines.push("");
+    lines.push(`Section: ${section.heading} (lines ${section.lineStart}-${section.lineEnd})`);
+  }
+  const text = guardText(warning + trimBlankLines(lines).join("\n"), "symbol");
+  if (opts.suppressStat !== true) recordReadStat("brief_view", fullSourceBytes, text, opts.spec);
+  return { text, code: 0 };
+}
+function runBriefMulti(file, symbols, opts) {
+  let anyFound = false;
+  const jsonOut = {};
+  const textBlocks = [];
+  for (const sym of symbols) {
+    const sub = runBriefCore({ ...opts, spec: `${file}::${sym}`, suppressStat: true });
+    if (sub.code === 0) anyFound = true;
+    if (opts.json === true) {
+      jsonOut[sym] = sub.code === 0 ? JSON.parse(sub.text) : { error: sub.text };
+      continue;
+    }
+    textBlocks.push(`${sym}:
+${sub.text}`);
+  }
+  const fullSourceBytes = sumFileSizes([resolveSpecPath(file, opts.projectRoot ?? process.cwd())]);
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
+  if (anyFound) recordReadStat("brief_view", fullSourceBytes, text, opts.spec);
+  return { text, code: anyFound ? 0 : 1 };
+}
+function runBriefCrossFile(pairs, opts) {
+  const distinctFiles = new Set(pairs.map((p) => p.file));
+  const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
+  let anyFound = false;
+  const jsonOut = {};
+  const textBlocks = [];
+  for (const { file, symbol } of pairs) {
+    const key = keyFor({ file, symbol });
+    const sub = runBriefCore({ ...opts, spec: `${file}::${symbol}`, suppressStat: true });
+    if (sub.code === 0) anyFound = true;
+    if (opts.json === true) {
+      jsonOut[key] = sub.code === 0 ? JSON.parse(sub.text) : { error: sub.text };
+      continue;
+    }
+    textBlocks.push(`${key}:
+${sub.text}`);
+  }
+  const fullSourceBytes = sumFileSizes([...distinctFiles].map((f) => resolveSpecPath(f, opts.projectRoot ?? process.cwd())));
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
+  if (anyFound) recordReadStat("brief_view", fullSourceBytes, text, opts.spec);
+  return { text, code: anyFound ? 0 : 1 };
+}
+function runBrief(opts) {
+  if (opts.limit !== void 0 && opts.limit <= 0) {
+    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    return 1;
+  }
+  const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
+  if (crossFilePairs !== null) {
+    const { text: text2, code: code2 } = runBriefCrossFile(crossFilePairs, opts);
+    if (code2 === 0) emit(text2);
+    else emitErr(text2);
+    return code2;
+  }
+  const { file, symbol } = parseReadSpec(opts.spec);
+  if (symbol !== void 0 && symbol !== "" && symbol.includes(",")) {
+    const multiSymbols = symbol.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    if (multiSymbols.length > 1) {
+      const { text: text2, code: code2 } = runBriefMulti(file, multiSymbols, opts);
+      if (code2 === 0) emit(text2);
+      else emitErr(text2);
+      return code2;
+    }
+  }
+  const { text, code } = runBriefCore(opts);
+  if (code === 0) emit(text);
+  else emitErr(text);
+  return code;
+}
+
+// src/read_section.ts
+init_define_import_meta_env();
+import * as fs from "node:fs";
+function htmlIdSectionFallback(filePath, heading) {
+  if (detectLanguage(filePath) !== "html") return null;
+  healStaleIndex(filePath);
+  const hit = querySymbols({ name: stripHtmlIdSpelling(heading, filePath), filePath, kind: "html_id", limit: 1 })[0];
+  if (hit === void 0) return null;
+  const text = readFileText(filePath);
+  if (text === null) return null;
+  const lines = text.split("\n");
+  return { heading: hit.name, content: lines.slice(hit.lineStart - 1, hit.lineEnd).join("\n"), lineStart: hit.lineStart, lineEnd: hit.lineEnd };
+}
+var AMBIGUOUS_HEADING_LIMIT = 10;
+function filterBodyByGrep(content, pattern) {
+  const matches = compileGrepMatcher(pattern);
+  const lines = content.split("\n");
+  const out = [];
+  let matched = 0;
+  let pendingHeading = null;
+  const unfenced = new Set(Array.from(eachUnfencedLine(lines), ([i]) => i));
+  for (const [i, line] of lines.entries()) {
+    const isHeading = unfenced.has(i) && matchAtxHeading(line, ATX_CLASS_BREAK_RE, true) !== null;
+    if (i === 0 && isHeading) out.push(line);
+    else if (isHeading) pendingHeading = line;
+    const hit = matches(line);
+    if (hit) matched++;
+    if (!hit || i === 0 && isHeading) continue;
+    if (pendingHeading !== null && pendingHeading !== line) out.push(pendingHeading);
+    pendingHeading = null;
+    out.push(line);
+  }
+  return { content: out.join("\n"), matched, total: lines.length };
+}
+function literalHeadingExists(filePath, heading) {
+  const ordinalMatch = /^([^#\r\n]+)#(\d+)$/.exec(heading);
+  const base = (ordinalMatch?.[1] ?? heading).trim().toLowerCase();
+  if (base.length === 0) return false;
+  return listSections(filePath, readFileText).some((h) => h.trim().toLowerCase() === base);
+}
+function findSectionSeparator(spec, projectRoot) {
+  const last = spec.lastIndexOf("::");
+  if (last <= 0) return last;
+  const isFile = (idx) => {
+    try {
+      return fs.statSync(resolveAgainstProjectRoot(spec.slice(0, idx), projectRoot)).isFile();
+    } catch {
+      return false;
+    }
+  };
+  if (isFile(last)) return last;
+  for (let idx = spec.indexOf("::"); idx !== -1 && idx < last; idx = spec.indexOf("::", idx + 1)) {
+    if (idx > 0 && isFile(idx)) return idx;
+  }
+  return last;
+}
+function runSection(opts) {
+  const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
+  if (crossFilePairs !== null) return runSectionCrossFile(crossFilePairs, opts);
+  const colonIdx = findSectionSeparator(opts.spec, opts.projectRoot);
+  if (colonIdx === -1) {
+    return { text: `Invalid section spec \u2014 expected "file::Heading", got: ${opts.spec}`, code: 1 };
+  }
+  const specFilePath = opts.spec.slice(0, colonIdx);
+  const filePath = resolveAgainstProjectRoot(specFilePath, opts.projectRoot);
+  const heading = opts.spec.slice(colonIdx + 2);
+  if (heading.includes(",") && !literalHeadingExists(filePath, heading)) {
+    const multiHeadings = heading.split(",").map((h) => h.trim()).filter((h) => h.length > 0);
+    if (multiHeadings.length > 1) return runSectionMulti(specFilePath, filePath, multiHeadings, opts);
+  }
+  const result = readSection(filePath, heading, readFileText) ?? htmlIdSectionFallback(filePath, heading);
+  if (result === null) {
+    if (!fs.existsSync(filePath)) {
+      return { text: `File not found: '${filePath}'`, code: 1 };
+    }
+    const ordSpec = /^(.*?)#(\d+)$/.exec(heading);
+    const ordBase = ordSpec?.[1]?.trim();
+    if (ordBase !== void 0 && ordBase.length > 0) {
+      const baseResult = readSection(filePath, ordBase, readFileText);
+      if (baseResult !== null) {
+        const total = baseResult.occurrences?.length ?? 1;
+        return {
+          text: `Heading '${ordBase}' has ${countNoun(total, "occurrence")} in '${specFilePath}'; valid ordinals are #1 to #${total}`,
+          code: 1
+        };
+      }
+    }
+    const messages = [`Section '${heading}' not found in '${filePath}'`];
+    const allHeadings = listSections(filePath, readFileText);
+    const available = filterSimilarHeadings(allHeadings, heading);
+    if (available.length > 0) messages.push(didYouMean(available));
+    else if (allHeadings.length === 0) messages.push(`'${specFilePath}' has no headings`);
+    else messages.push(`Try: token-goat outline ${specFilePath}`);
+    return { text: messages.join("\n"), code: 1 };
+  }
+  if (result.occurrences !== void 0) {
+    const lines = [
+      `Ambiguous heading '${heading}' in '${specFilePath}': ${countNoun(result.occurrences.length, "heading")} match. Retry with one of the qualified commands below to pick one:`
+    ];
+    for (const [i, line] of result.occurrences.slice(0, AMBIGUOUS_HEADING_LIMIT).entries()) {
+      lines.push(`  - line ${line}  ->  token-goat section "${specFilePath}::${heading}#${i + 1}"`);
+    }
+    if (result.occurrences.length > AMBIGUOUS_HEADING_LIMIT) {
+      lines.push(`  (${result.occurrences.length - AMBIGUOUS_HEADING_LIMIT} more not shown)`);
+    }
+    return { text: lines.join("\n"), code: 1 };
+  }
+  const kind = result.redirectedFrom !== void 0 ? "section_replacement" : "section_read";
+  const fullSourceBytes = sumFileSizes([filePath]);
+  let content = result.content;
+  let lineEnd = result.lineEnd;
+  let truncatedNotice = "";
+  let grepNote = "";
+  let grepStats = null;
+  if (opts.grep !== void 0) {
+    const filtered = filterBodyByGrep(content, opts.grep);
+    grepStats = { matched: filtered.matched, total: filtered.total };
+    grepNote = filtered.matched === 0 ? `
+${grepFilteredToEmptyNotice(filtered.total, opts.grep, "line", "lines")}` : `
+${filtered.matched} of ${filtered.total} lines matched`;
+    content = filtered.matched === 0 ? "" : filtered.content;
+  }
+  if (opts.maxLines !== void 0 && opts.maxLines > 0) {
+    const lines = content.split("\n");
+    if (lines.length > opts.maxLines) {
+      const remaining = lines.length - opts.maxLines;
+      content = lines.slice(0, opts.maxLines).join("\n");
+      if (opts.grep === void 0) lineEnd = Math.min(result.lineEnd, result.lineStart + opts.maxLines - 1);
+      truncatedNotice = `
+... (${countNoun(remaining, "more line")} not shown; pass a larger --max-lines or omit to read full section)`;
+    }
+  }
+  if (opts.json === true) {
+    const jsonPayload = {
+      ...result,
+      content,
+      lineEnd,
+      ...grepStats !== null ? { grep: opts.grep, matchedLines: grepStats.matched, sectionLines: grepStats.total } : {},
+      ...opts.maxLines !== void 0 && opts.maxLines > 0 ? {
+        totalLines: result.content.split("\n").length,
+        shownLines: content.split("\n").length,
+        truncated: truncatedNotice.length > 0
+      } : {}
+    };
+    const text2 = displaySafeJson(jsonPayload);
+    if (opts.suppressStat !== true) recordReadStat(kind, fullSourceBytes, text2, heading);
+    return { text: text2, code: 0 };
+  }
+  const redirectNote = result.redirectedFrom !== void 0 ? ` (redirected from: '${result.redirectedFrom}')` : "";
+  const text = guardText(
+    `# ${result.heading} \u2014 ${filePath}:${result.lineStart}-${lineEnd}${redirectNote}${content.length > 0 ? `
+${content}` : ""}${truncatedNotice}${grepNote}`,
+    "heading"
+  );
+  if (opts.suppressStat !== true) recordReadStat(kind, fullSourceBytes, text, heading);
+  return { text, code: 0 };
+}
+function runSectionMulti(specFilePath, resolvedFilePath, headings, opts) {
+  let anyFound = false;
+  const jsonOut = {};
+  const textBlocks = [];
+  const includedSections = [];
+  for (const heading of headings) {
+    const sectionResult = readSection(resolvedFilePath, heading, readFileText);
+    if (sectionResult !== null) {
+      const parent = includedSections.find(
+        (p) => sectionResult.lineStart >= p.lineStart && sectionResult.lineEnd <= p.lineEnd
+      );
+      if (parent !== void 0) {
+        anyFound = true;
+        const notice = `(already included in section '${parent.heading}', lines ${sectionResult.lineStart}-${sectionResult.lineEnd})`;
+        if (opts.json === true) {
+          jsonOut[heading] = {
+            heading: sectionResult.heading,
+            subsumedBy: parent.heading,
+            lineStart: sectionResult.lineStart,
+            lineEnd: sectionResult.lineEnd,
+            notice
+          };
+          continue;
+        }
+        textBlocks.push(
+          `${heading}:
+# ${sectionResult.heading} \u2014 ${specFilePath}:${sectionResult.lineStart}-${sectionResult.lineEnd}
+${notice}`
+        );
+        continue;
+      }
+      includedSections.push({
+        heading: sectionResult.heading,
+        lineStart: sectionResult.lineStart,
+        lineEnd: sectionResult.lineEnd
+      });
+    }
+    const sub = runSection({ ...opts, spec: `${specFilePath}::${heading}`, suppressStat: true });
+    if (sub.code === 0) anyFound = true;
+    if (opts.json === true) {
+      jsonOut[heading] = sub.code === 0 ? JSON.parse(sub.text) : { error: sub.text };
+      continue;
+    }
+    textBlocks.push(`${heading}:
+${sub.text}`);
+  }
+  const fullSourceBytes = sumFileSizes([resolvedFilePath]);
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
+  if (anyFound) recordReadStat("section_read", fullSourceBytes, text, opts.spec);
+  return { text, code: anyFound ? 0 : 1 };
+}
+function runSectionCrossFile(pairs, opts) {
+  let anyFound = false;
+  const jsonOut = {};
+  const textBlocks = [];
+  const includedByFile = /* @__PURE__ */ new Map();
+  const distinctFiles = new Set(pairs.map((p) => p.file));
+  const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
+  for (const { file, symbol: heading } of pairs) {
+    const resolved = resolveAgainstProjectRoot(file, opts.projectRoot);
+    const sectionResult = readSection(resolved, heading, readFileText);
+    const key = keyFor({ file, symbol: heading });
+    const fileIncluded = includedByFile.get(resolved) ?? [];
+    if (sectionResult !== null) {
+      const parent = fileIncluded.find(
+        (p) => sectionResult.lineStart >= p.lineStart && sectionResult.lineEnd <= p.lineEnd
+      );
+      if (parent !== void 0) {
+        anyFound = true;
+        const notice = `(already included in section '${parent.heading}', lines ${sectionResult.lineStart}-${sectionResult.lineEnd})`;
+        if (opts.json === true) {
+          jsonOut[key] = {
+            heading: sectionResult.heading,
+            subsumedBy: parent.heading,
+            lineStart: sectionResult.lineStart,
+            lineEnd: sectionResult.lineEnd,
+            notice
+          };
+          continue;
+        }
+        textBlocks.push(
+          `${key}:
+# ${sectionResult.heading} \u2014 ${file}:${sectionResult.lineStart}-${sectionResult.lineEnd}
+${notice}`
+        );
+        continue;
+      }
+      fileIncluded.push({
+        heading: sectionResult.heading,
+        lineStart: sectionResult.lineStart,
+        lineEnd: sectionResult.lineEnd
+      });
+      includedByFile.set(resolved, fileIncluded);
+    }
+    const sub = runSection({ ...opts, spec: `${file}::${heading}`, suppressStat: true });
+    if (sub.code === 0) anyFound = true;
+    if (opts.json === true) {
+      jsonOut[key] = sub.code === 0 ? JSON.parse(sub.text) : { error: sub.text };
+      continue;
+    }
+    textBlocks.push(`${key}:
+${sub.text}`);
+  }
+  const text = opts.json === true ? displaySafeJson(jsonOut) : textBlocks.join("\n\n");
+  if (anyFound) {
+    const fullSourceBytes = sumFileSizes(Array.from(distinctFiles, (f) => resolveAgainstProjectRoot(f, opts.projectRoot)));
+    recordReadStat("section_read", fullSourceBytes, text, opts.spec);
+  }
+  return { text, code: anyFound ? 0 : 1 };
+}
+
+// src/read_inspect.ts
+init_define_import_meta_env();
+import * as path from "node:path";
+
+// src/archive_query.ts
+init_define_import_meta_env();
+var loadFflate = createLazyModuleLoader(
+  async () => await import("fflate"),
+  "archive reading disabled (fflate unavailable)"
+);
+var ArchiveDependencyMissingError = class extends Error {
+  constructor() {
+    super("fflate is not installed; run `npm install fflate` to enable zip-list/zip-read");
+    this.name = "ArchiveDependencyMissingError";
+  }
+};
+async function requireFflate() {
+  const fflate = await loadFflate();
+  if (!fflate) throw new ArchiveDependencyMissingError();
+  return fflate;
+}
+async function listZipEntries(data) {
+  const fflate = await requireFflate();
+  const entries = [];
+  fflate.unzipSync(data, {
+    filter: (file) => {
+      entries.push({
+        path: file.name,
+        size: file.originalSize,
+        compressedSize: file.size,
+        isDirectory: file.name.endsWith("/")
+      });
+      return false;
+    }
+  });
+  entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return entries;
+}
+function formatZipList(entries) {
+  if (entries.length === 0) return "(no entries found)";
+  return entries.map((e) => `${String(e.size).padStart(10)}  ${displaySafeText(e.path)}`).join("\n");
+}
+async function extractZipEntry(data, entryPath) {
+  const fflate = await requireFflate();
+  const result = unzipBounded(fflate, data, { limitBytes: MAX_ZIP_OUTPUT_BYTES, shouldExtract: (name) => name === entryPath });
+  return result[entryPath];
+}
+
+// src/coverage_query.ts
+init_define_import_meta_env();
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+function collapseLineRanges(sortedLines) {
+  const ranges = [];
+  for (const n of sortedLines) {
+    const last = ranges[ranges.length - 1];
+    if (last !== void 0 && n === last.end + 1) {
+      last.end = n;
+    } else {
+      ranges.push({ start: n, end: n });
+    }
+  }
+  return ranges;
+}
+function hasGap(f) {
+  return f.uncoveredLineCount > 0 || f.uncoveredFunctions.length > 0 || f.uncoveredBranches.length > 0 || f.functionsHit < f.functionsTotal || f.branchesHit < f.branchesTotal;
+}
+function rankAndFilter(files) {
+  const withGaps = files.filter(hasGap);
+  withGaps.sort((a, b) => {
+    const byCount = b.uncoveredLineCount - a.uncoveredLineCount;
+    if (byCount !== 0) return byCount;
+    return a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0;
+  });
+  return withGaps;
+}
+function detectCoverageFormat(text) {
+  let parsed;
+  let isJson = true;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    isJson = false;
+  }
+  if (isJson) {
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("not a recognized coverage report (JSON root is not an object of per-file entries)");
+    }
+    const entries = Object.entries(parsed).filter(([k]) => k !== "total");
+    const looksFinal = entries.some(
+      ([, v]) => typeof v === "object" && v !== null && "statementMap" in v && "s" in v
+    );
+    if (looksFinal) return "istanbul-final";
+    const looksSummary = entries.some(
+      ([, v]) => typeof v === "object" && v !== null && "lines" in v && "statements" in v && "functions" in v && "branches" in v
+    );
+    if (looksSummary) return "istanbul-summary";
+    const total = parsed["total"];
+    if (entries.length === 0 && typeof total === "object" && total !== null && "lines" in total && "statements" in total && "functions" in total && "branches" in total) {
+      return "istanbul-summary";
+    }
+    if (entries.length === 0) return "istanbul-final";
+    throw new Error("not a recognized coverage report (JSON does not match Istanbul coverage-final or coverage-summary shape)");
+  }
+  const trimmedStart = text.replace(/^\s+/, "");
+  if (/^(TN:|SF:)/.test(trimmedStart)) return "lcov";
+  throw new Error("could not detect coverage report format (not valid LCOV, and not valid JSON)");
+}
+function buildLcovFileGaps(acc) {
+  const linesTotal = acc.daLines.size;
+  const uncoveredLineNums = [...acc.daLines.entries()].filter(([, hits]) => hits === 0).map(([ln]) => ln).sort((a, b) => a - b);
+  const linesHit = linesTotal - uncoveredLineNums.length;
+  const functionsTotal = acc.fnRecords.size;
+  const uncoveredFunctions = [];
+  for (const { name, line } of acc.fnRecords.values()) {
+    if ((acc.fnHits.get(name) ?? 0) === 0) uncoveredFunctions.push({ name, line });
+  }
+  uncoveredFunctions.sort((a, b) => a.line - b.line);
+  const functionsHit = functionsTotal - uncoveredFunctions.length;
+  const branchesTotal = acc.brda.length;
+  const uncoveredBranches = acc.brda.filter((b) => b.hits === null || b.hits === 0).map((b) => ({ line: b.line }));
+  const branchesHit = branchesTotal - uncoveredBranches.length;
+  return {
+    filePath: acc.filePath,
+    linesTotal,
+    linesHit,
+    functionsTotal,
+    functionsHit,
+    branchesTotal,
+    branchesHit,
+    uncoveredLineRanges: collapseLineRanges(uncoveredLineNums),
+    uncoveredLineCount: uncoveredLineNums.length,
+    uncoveredFunctions,
+    uncoveredBranches,
+    summaryOnly: false
+  };
+}
+function parseLcov(text) {
+  const files = [];
+  let cur = null;
+  const closeCurrent = () => {
+    if (cur === null) return;
+    files.push(buildLcovFileGaps(cur));
+    cur = null;
+  };
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "") continue;
+    if (line.startsWith("SF:")) {
+      closeCurrent();
+      cur = { filePath: line.slice(3).trim(), daLines: /* @__PURE__ */ new Map(), fnRecords: /* @__PURE__ */ new Map(), fnHits: /* @__PURE__ */ new Map(), brda: [] };
+      continue;
+    }
+    if (cur === null) continue;
+    if (line === "end_of_record") {
+      closeCurrent();
+      continue;
+    }
+    if (line.startsWith("DA:")) {
+      const [rawLineNo, rawHits] = line.slice(3).split(",");
+      const lineNo = Number.parseInt(rawLineNo ?? "", 10);
+      const hits = Number.parseInt(rawHits ?? "", 10);
+      if (Number.isFinite(lineNo) && Number.isFinite(hits)) cur.daLines.set(lineNo, hits);
+      continue;
+    }
+    if (line.startsWith("FN:")) {
+      const rest = line.slice(3);
+      const comma = rest.indexOf(",");
+      if (comma !== -1) {
+        const lineNo = Number.parseInt(rest.slice(0, comma), 10);
+        let name = rest.slice(comma + 1);
+        const comma2 = name.indexOf(",");
+        if (comma2 !== -1 && /^\d+$/.test(name.slice(0, comma2))) {
+          name = name.slice(comma2 + 1);
+        }
+        if (Number.isFinite(lineNo)) cur.fnRecords.set(`${name}
+${lineNo}`, { name, line: lineNo });
+      }
+      continue;
+    }
+    if (line.startsWith("FNDA:")) {
+      const rest = line.slice(5);
+      const comma = rest.indexOf(",");
+      if (comma !== -1) {
+        const hits = Number.parseInt(rest.slice(0, comma), 10);
+        const name = rest.slice(comma + 1);
+        if (Number.isFinite(hits)) cur.fnHits.set(name, (cur.fnHits.get(name) ?? 0) + hits);
+      }
+      continue;
+    }
+    if (line.startsWith("BRDA:")) {
+      const parts = line.slice(5).split(",");
+      const lineNo = Number.parseInt(parts[0] ?? "", 10);
+      const rawHits = parts[3];
+      if (Number.isFinite(lineNo)) {
+        const hits = rawHits === "-" ? null : Number.parseInt(rawHits ?? "", 10);
+        cur.brda.push({ line: lineNo, hits: hits !== null && Number.isFinite(hits) ? hits : null });
+      }
+      continue;
+    }
+  }
+  closeCurrent();
+  return { format: "lcov", files: rankAndFilter(files) };
+}
+function parseIstanbulFinal(data) {
+  const files = [];
+  for (const [filePath, entryRaw] of Object.entries(data)) {
+    if (typeof entryRaw !== "object" || entryRaw === null) continue;
+    const entry = entryRaw;
+    const statementMap = entry["statementMap"] ?? {};
+    const s = entry["s"] ?? {};
+    const fnMap = entry["fnMap"] ?? {};
+    const f = entry["f"] ?? {};
+    const branchMap = entry["branchMap"] ?? {};
+    const b = entry["b"] ?? {};
+    const lineCovered = /* @__PURE__ */ new Map();
+    for (const [id, hits] of Object.entries(s)) {
+      const stmt = statementMap[id];
+      if (stmt === void 0 || stmt.start === void 0) continue;
+      const ln = stmt.start.line;
+      lineCovered.set(ln, (lineCovered.get(ln) ?? false) || num(hits) > 0);
+    }
+    const linesTotal = lineCovered.size;
+    const uncoveredLineNums = [...lineCovered.entries()].filter(([, covered]) => !covered).map(([ln]) => ln).sort((a, b2) => a - b2);
+    const linesHit = linesTotal - uncoveredLineNums.length;
+    let functionsTotal = 0;
+    const uncoveredFunctions = [];
+    for (const [id, fnInfo] of Object.entries(fnMap)) {
+      functionsTotal++;
+      if (num(f[id]) === 0) {
+        const line = (fnInfo.decl?.start !== void 0 ? fnInfo.decl.start.line : void 0) ?? (fnInfo.loc?.start !== void 0 ? fnInfo.loc.start.line : void 0) ?? 0;
+        uncoveredFunctions.push({ name: fnInfo.name !== void 0 && fnInfo.name !== "" ? fnInfo.name : "(anonymous)", line });
+      }
+    }
+    uncoveredFunctions.sort((a, b2) => a.line - b2.line);
+    const functionsHit = functionsTotal - uncoveredFunctions.length;
+    let branchesTotal = 0;
+    const uncoveredBranches = [];
+    for (const [id, hitsArrRaw] of Object.entries(b)) {
+      const branchInfo = branchMap[id];
+      const hitsArr = Array.isArray(hitsArrRaw) ? hitsArrRaw : [];
+      branchesTotal += hitsArr.length;
+      hitsArr.forEach((hits, idx) => {
+        if (num(hits) === 0) {
+          const locStart = branchInfo?.locations?.[idx]?.start;
+          const branchStart = branchInfo?.loc?.start;
+          const line = (locStart !== void 0 ? locStart.line : void 0) ?? (branchStart !== void 0 ? branchStart.line : void 0) ?? 0;
+          uncoveredBranches.push({ line });
+        }
+      });
+    }
+    const branchesHit = branchesTotal - uncoveredBranches.length;
+    files.push({
+      filePath,
+      linesTotal,
+      linesHit,
+      functionsTotal,
+      functionsHit,
+      branchesTotal,
+      branchesHit,
+      uncoveredLineRanges: collapseLineRanges(uncoveredLineNums),
+      uncoveredLineCount: uncoveredLineNums.length,
+      uncoveredFunctions,
+      uncoveredBranches,
+      summaryOnly: false
+    });
+  }
+  return { format: "istanbul-final", files: rankAndFilter(files) };
+}
+function parseIstanbulSummary(data) {
+  const files = [];
+  for (const [filePath, entryRaw] of Object.entries(data)) {
+    if (filePath === "total") continue;
+    if (typeof entryRaw !== "object" || entryRaw === null) continue;
+    const entry = entryRaw;
+    const lines = entry["lines"] ?? {};
+    const functions = entry["functions"] ?? {};
+    const branches = entry["branches"] ?? {};
+    const linesTotal = num(lines.total);
+    const linesHit = num(lines.covered);
+    const functionsTotal = num(functions.total);
+    const functionsHit = num(functions.covered);
+    const branchesTotal = num(branches.total);
+    const branchesHit = num(branches.covered);
+    files.push({
+      filePath,
+      linesTotal,
+      linesHit,
+      functionsTotal,
+      functionsHit,
+      branchesTotal,
+      branchesHit,
+      uncoveredLineRanges: [],
+      uncoveredLineCount: Math.max(0, linesTotal - linesHit),
+      uncoveredFunctions: [],
+      uncoveredBranches: [],
+      summaryOnly: true
+    });
+  }
+  return { format: "istanbul-summary", files: rankAndFilter(files) };
+}
+function parseCoverageReport(text) {
+  text = stripBom(text);
+  const format = detectCoverageFormat(text);
+  if (format === "lcov") return parseLcov(text);
+  const data = JSON.parse(text);
+  return format === "istanbul-final" ? parseIstanbulFinal(data) : parseIstanbulSummary(data);
+}
+function endsWithPathBoundaryLocal(full, suffix) {
+  if (!full.endsWith(suffix)) return false;
+  if (full.length === suffix.length) return true;
+  return full[full.length - suffix.length - 1] === "/";
+}
+function filterCoverageGapsByFile(report, filePathQuery) {
+  const query = foldPath(normalizePath(filePathQuery));
+  const files = report.files.filter((f) => {
+    const candidate = foldPath(normalizePath(f.filePath));
+    return candidate === query || endsWithPathBoundaryLocal(candidate, query) || endsWithPathBoundaryLocal(query, candidate);
+  });
+  return { format: report.format, files };
+}
+function formatRanges(ranges) {
+  return ranges.map((r) => r.start === r.end ? String(r.start) : `${r.start}-${r.end}`).join(", ");
+}
+function formatFileGaps(f) {
+  const lines = [displaySafeText(f.filePath)];
+  lines.push(`  lines: ${f.linesHit}/${f.linesTotal}  functions: ${f.functionsHit}/${f.functionsTotal}  branches: ${f.branchesHit}/${f.branchesTotal}`);
+  if (f.summaryOnly) {
+    lines.push("  (summary-only report -- no per-line/function/branch detail available)");
+    return lines.join("\n");
+  }
+  if (f.uncoveredLineRanges.length > 0) {
+    lines.push(`  uncovered lines: ${formatRanges(f.uncoveredLineRanges)}`);
+  }
+  if (f.uncoveredFunctions.length > 0) {
+    lines.push("  uncovered functions:");
+    for (const fn of f.uncoveredFunctions) lines.push(`    ${displaySafeText(fn.name)} (line ${fn.line})`);
+  }
+  if (f.uncoveredBranches.length > 0) {
+    const branchLines = [...new Set(f.uncoveredBranches.map((br) => br.line))].sort((a, b) => a - b);
+    lines.push(`  uncovered branches at line${branchLines.length === 1 ? "" : "s"}: ${branchLines.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function formatCoverageGaps(report) {
+  if (report.files.length === 0) return "No coverage gaps found -- 100% coverage.";
+  return report.files.map(formatFileGaps).join("\n\n");
+}
+
+// src/read_inspect.ts
+function archiveReadFailure(err, file) {
+  if (err instanceof ArchiveDependencyMissingError || err instanceof ZipOutputTooLargeError) return err.message;
+  return `Failed to read archive (not a valid zip-format file): ${file}`;
+}
+async function runZipList(opts) {
+  let data;
+  try {
+    data = readFileBytes(opts.file);
+  } catch (err) {
+    if (err instanceof ZipInputTooLargeError) {
+      emitErr(err.message);
+      return 1;
+    }
+    throw err;
+  }
+  if (data === null) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  let entries;
+  try {
+    entries = await listZipEntries(data);
+  } catch (err) {
+    emitErr(archiveReadFailure(err, opts.file));
+    return 1;
+  }
+  const fullSourceBytes = sumFileSizes([opts.file]);
+  if (opts.json === true) {
+    const jsonText = displaySafeJson(entries, 0);
+    emit(jsonText);
+    recordReadStat("zip_list", fullSourceBytes, jsonText, opts.file);
+  } else {
+    const text = formatZipList(entries);
+    emitGuarded(text, "zip-list");
+    recordReadStat("zip_list", fullSourceBytes, text, opts.file);
+  }
+  return 0;
+}
+async function runZipRead(opts) {
+  let data;
+  try {
+    data = readFileBytes(opts.file);
+  } catch (err) {
+    if (err instanceof ZipInputTooLargeError) {
+      emitErr(err.message);
+      return 1;
+    }
+    throw err;
+  }
+  if (data === null) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  let entries;
+  let content;
+  try {
+    entries = await listZipEntries(data);
+    content = await extractZipEntry(data, opts.entry);
+  } catch (err) {
+    emitErr(archiveReadFailure(err, opts.file));
+    return 1;
+  }
+  const matchedEntry = entries.find((e) => e.path === opts.entry);
+  if (matchedEntry?.isDirectory === true) {
+    emitErr(`Entry '${opts.entry}' is a directory, not a file, in '${opts.file}'`);
+    return 1;
+  }
+  if (content === void 0) {
+    const messages = [`Entry '${opts.entry}' not found in '${opts.file}'`];
+    const closes = rankSimilarNames(entries.map((e) => e.path), opts.entry);
+    if (closes.length > 0) messages.push(didYouMean(closes));
+    else if (entries.length > 0) messages.push(`Try: token-goat zip-list ${opts.file}`);
+    emitErr(messages.join("\n"));
+    return 1;
+  }
+  const buf = Buffer.from(content);
+  const text = isValidUtf8(buf) ? buf.toString("utf-8") : "[binary content elided by token-goat]";
+  const fullSourceBytes = sumFileSizes([opts.file]);
+  if (opts.json === true) {
+    const jsonText = displaySafeJson({ path: opts.entry, text }, 0);
+    emit(jsonText);
+    recordReadStat("zip_read", fullSourceBytes, jsonText, opts.entry);
+  } else {
+    emitGuarded(text, "zip-read");
+    recordReadStat("zip_read", fullSourceBytes, text, opts.entry);
+  }
+  return 0;
+}
+function runSqliteSchema(opts) {
+  try {
+    const schema = getSqliteSchema(opts.file);
+    const fullSourceBytes = sumFileSizes([opts.file]);
+    if (opts.json === true) {
+      const jsonText = displaySafeJson(schema, 0);
+      emit(jsonText);
+      recordReadStat("sqlite_schema", fullSourceBytes, jsonText, opts.file);
+    } else {
+      const text = formatSqliteSchema(schema);
+      emit(text);
+      recordReadStat("sqlite_schema", fullSourceBytes, text, opts.file);
+    }
+    return 0;
+  } catch (e) {
+    emitErr(extractErrorMessage(e));
+    return 1;
+  }
+}
+function runSqliteTables(opts) {
+  try {
+    const tables = getSqliteTables(opts.file);
+    const fullSourceBytes = sumFileSizes([opts.file]);
+    if (opts.json === true) {
+      const jsonText = displaySafeJson(tables, 0);
+      emit(jsonText);
+      recordReadStat("sqlite_tables", fullSourceBytes, jsonText, opts.file);
+    } else {
+      const text = formatSqliteTables(tables);
+      emit(text);
+      recordReadStat("sqlite_tables", fullSourceBytes, text, opts.file);
+    }
+    return 0;
+  } catch (e) {
+    emitErr(extractErrorMessage(e));
+    return 1;
+  }
+}
+function runSqliteQuery(opts) {
+  let head;
+  try {
+    head = opts.head !== void 0 ? requireNonNegativeStrictInt("--head", opts.head) : void 0;
+  } catch (e) {
+    emitErr(extractErrorMessage(e));
+    return 1;
+  }
+  try {
+    const result = runReadOnlySqliteQuery(opts.file, opts.sql);
+    const totalCount = result.rows.length;
+    const headTruncated = head !== void 0 && result.rows.length > head;
+    const rows = head !== void 0 ? result.rows.slice(0, head) : result.rows;
+    if (opts.json === true) {
+      const capped = guardJsonRows(rows);
+      const jsonText = displaySafeJson({
+        columns: result.columns,
+        items: capped.items,
+        truncated: capped.truncated || headTruncated || result.rowCapped,
+        totalCount,
+        rowCapped: result.rowCapped
+      }, 0);
+      emit(jsonText);
+      const uncappedFull = guardJsonRows(result.rows);
+      const baselineJsonText = displaySafeJson({
+        columns: result.columns,
+        items: uncappedFull.items,
+        truncated: uncappedFull.truncated || result.rowCapped,
+        totalCount,
+        rowCapped: result.rowCapped
+      }, 0);
+      recordReadStat("sqlite_query", Buffer.byteLength(baselineJsonText, "utf8"), jsonText, opts.file);
+    } else {
+      const text = formatSqliteQueryTable({ ...result, rows }, { headTruncated });
+      emit(text);
+      const baselineText = formatSqliteQueryTable({ ...result, rows: result.rows }, { headTruncated: false });
+      recordReadStat("sqlite_query", Buffer.byteLength(baselineText, "utf8"), text, opts.file);
+    }
+    return 0;
+  } catch (e) {
+    emitErr(extractErrorMessage(e));
+    return 1;
+  }
+}
+function runCoverageReportGaps(opts) {
+  const text = readFileText(opts.file);
+  if (text === null) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  let report;
+  try {
+    report = parseCoverageReport(text);
+  } catch (e) {
+    emitErr(`Failed to parse coverage report (not valid LCOV or Istanbul JSON): ${opts.file}
+${extractErrorMessage(e)}`);
+    return 1;
+  }
+  const scoped = opts.fileFilter !== void 0 ? filterCoverageGapsByFile(report, opts.fileFilter) : report;
+  const fullSourceBytes = sumFileSizes([opts.file]);
+  if (opts.json === true) {
+    const jsonText = displaySafeJson(scoped, 0);
+    emit(jsonText);
+    recordReadStat("coverage_report_gaps", fullSourceBytes, jsonText, opts.file);
+  } else {
+    const text2 = formatCoverageGaps(scoped);
+    emitGuarded(text2, "coverage-report-gaps");
+    recordReadStat("coverage_report_gaps", fullSourceBytes, text2, opts.file);
+  }
+  return 0;
+}
+function stripInlineComment(s) {
+  let inQuote = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inQuote !== null) {
+      if (ch === "\\" && i + 1 < s.length) {
+        i++;
+        continue;
+      }
+      if (ch === inQuote) inQuote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inQuote = ch;
+      continue;
+    }
+    if (ch === "#" || ch === ";") {
+      return s.slice(0, i);
+    }
+  }
+  return s;
+}
+function stripPairedQuotes(s) {
+  if (s.length >= 2) {
+    const first = s[0];
+    const last = s[s.length - 1];
+    if ((first === '"' || first === "'") && first === last) {
+      return s.slice(1, -1);
+    }
+  }
+  return s;
+}
+function lookupYaml(lines, key) {
+  const parts = key.split(".");
+  let depth = 0;
+  let parentIndent = -1;
+  let childIndent = -1;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const indent = line.length - line.trimStart().length;
+    if (depth > 0 && indent <= parentIndent) return null;
+    if (childIndent !== -1 && indent !== childIndent) continue;
+    const colon = trimmed.indexOf(":");
+    if (colon < 0) continue;
+    if (childIndent === -1) childIndent = indent;
+    const k = trimmed.slice(0, colon).trim();
+    if (k !== parts[depth]) continue;
+    if (depth === parts.length - 1) {
+      return stripPairedQuotes(trimmed.slice(colon + 1).trim());
+    }
+    parentIndent = indent;
+    childIndent = -1;
+    depth++;
+  }
+  return null;
+}
+function extractFrontmatter(lines) {
+  if (lines[0]?.trim() !== "---") return null;
+  let j = 1;
+  while (j < lines.length && lines[j]?.trim() !== "---") {
+    j++;
+  }
+  if (j >= lines.length) return null;
+  return lines.slice(1, j);
+}
+function runConfigGet(opts) {
+  const text = readFileText(opts.file);
+  if (text === null) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  const frontmatterLines = extractFrontmatter(text.split(/\r?\n/));
+  if (frontmatterLines !== null) {
+    const value = lookupYaml(frontmatterLines, opts.key);
+    if (value === null) {
+      emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+      return 1;
+    }
+    emit(value);
+    return 0;
+  }
+  const ext = path.extname(opts.file).toLowerCase();
+  if (ext === ".json" || ext === ".jsonc") {
+    try {
+      let obj = parseJsonOrJsonc(text);
+      for (const part of opts.key.split(".")) {
+        if (typeof obj !== "object" || obj === null) {
+          emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+          return 1;
+        }
+        obj = obj[part];
+        if (obj === void 0) {
+          emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+          return 1;
+        }
+      }
+      emit(displaySafeJson(obj, 0));
+      return 0;
+    } catch {
+      emitErr(`Failed to parse JSON: ${opts.file}`);
+      return 1;
+    }
+  }
+  if (ext === ".yaml" || ext === ".yml") {
+    const value = lookupYaml(text.split(/\r?\n/), opts.key);
+    if (value === null) {
+      emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+      return 1;
+    }
+    emit(value);
+    return 0;
+  }
+  if (ext === ".toml") {
+    const toml = lookupToml(text, opts.key);
+    if (toml !== void 0) {
+      if (toml === null) {
+        emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+        return 1;
+      }
+      emit(toml);
+      return 0;
+    }
+  }
+  const flavour = flatKeyFlavour(opts.file);
+  const lines = text.split("\n");
+  const keyParts = opts.key.split(".");
+  const attempts = [{ section: "", leaf: opts.key }];
+  if (keyParts.length > 1) attempts.push({ section: keyParts.slice(0, -1).join("."), leaf: keyParts.at(-1) ?? opts.key });
+  for (const attempt of attempts) {
+    const value = lookupFlatKey(lines, attempt.section, attempt.leaf, flavour);
+    if (value !== null) {
+      if (ext === ".toml" && isTomlFragment(value)) {
+        emitErr(`Key '${opts.key}' in ${opts.file} spans several lines and the file is not valid TOML, so it cannot be read whole`);
+        return 1;
+      }
+      emit(value);
+      return 0;
+    }
+  }
+  emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+  return 1;
+}
+function isTomlFragment(v) {
+  if (v === '"' || v === "'" || v.startsWith('"""') || v.startsWith("'''")) return true;
+  return v.startsWith("[") && !v.endsWith("]") || v.startsWith("{") && !v.endsWith("}");
+}
+var TOML_BARE_KEY = /^[A-Za-z0-9_-]+$/;
+function splitTomlKeyPath(key) {
+  const zero = tomlProbePath(key, 0);
+  const one = tomlProbePath(key, 1);
+  if (zero === null || one === null || JSON.stringify(zero) !== JSON.stringify(one)) return key.split(".").map((name) => ({ name, joinable: true }));
+  return zero.map((name) => ({ name, joinable: TOML_BARE_KEY.test(name) }));
+}
+function tomlProbePath(key, value) {
+  const parts = [];
+  try {
+    let node = parse(`${key} = ${value}`);
+    while (typeof node === "object" && node !== null && !Array.isArray(node)) {
+      const keys = Object.keys(node);
+      if (keys.length !== 1) return null;
+      const k = keys[0];
+      parts.push(k);
+      node = node[k];
+    }
+    return node === value && parts.length > 0 ? parts : null;
+  } catch {
+    return null;
+  }
+}
+function resolveTomlKey(node, parts) {
+  if (parts.length === 0) return node;
+  if (typeof node !== "object" || node === null || Array.isArray(node) || node instanceof Date) return void 0;
+  const table = node;
+  for (let n = 1; n <= parts.length; n++) {
+    if (n > 1 && !(parts[0].joinable && parts[n - 1].joinable)) break;
+    const head = parts.slice(0, n).map((p) => p.name).join(".");
+    if (!Object.hasOwn(table, head)) continue;
+    const found = resolveTomlKey(table[head], parts.slice(n));
+    if (found !== void 0) return found;
+  }
+  return void 0;
+}
+function lookupToml(text, key) {
+  let doc;
+  try {
+    doc = parse(text);
+  } catch {
+    return void 0;
+  }
+  const found = resolveTomlKey(doc, splitTomlKeyPath(key));
+  if (found === void 0) return null;
+  if (typeof found === "string") return found;
+  if (typeof found === "object" && found !== null && !(found instanceof Date)) {
+    return displaySafeJson(JSON.parse(JSON.stringify(found, (_k, x) => typeof x === "bigint" ? x.toString() : x)), 0);
+  }
+  return String(found);
+}
+function flatKeyFlavour(file) {
+  const base = (file.split(/[\\/]/).pop() ?? "").toLowerCase();
+  if (base.endsWith(".properties")) return "properties";
+  if (/^\.env(?:\.|$)/.test(base) || base.endsWith(".env")) return "env";
+  return "ini";
+}
+function lookupFlatKey(lines, section, leaf, flavour) {
+  const prefix = flavour === "env" ? "(?:export[ \\t]+)?" : "";
+  const separator = flavour === "properties" ? "(?:[ \\t]*[=:][ \\t]*|[ \\t]+)" : "\\s*=\\s*";
+  const lineRe = new RegExp(`^${prefix}${escapeRegExp(leaf)}${separator}(.*)$`);
+  let currentSection = "";
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const headerMatch = flavour === "properties" ? null : /^\[([^\]\r\n]+)\]\s*(?:[;#].*)?$/.exec(trimmed);
+    if (headerMatch) {
+      currentSection = (headerMatch[1] ?? "").trim();
+      continue;
+    }
+    if (currentSection !== section) continue;
+    const m = lineRe.exec(trimmed);
+    if (m === null) continue;
+    const raw = m[1] ?? "";
+    return stripPairedQuotes((flavour === "properties" ? raw : stripInlineComment(raw)).trim());
+  }
+  return null;
+}
+function runPerFileEmitting(files, label, run) {
+  let anyOk = false;
+  files.forEach((file, i) => {
+    if (i > 0) emit("");
+    emit(`# ${label}: ${file}`);
+    if (run(file) === 0) anyOk = true;
+  });
+  return anyOk ? 0 : 1;
+}
+function runExports(opts) {
+  const multiFiles = opts.file.split(",").map((f) => f.trim()).filter(Boolean);
+  if (multiFiles.length > 1) return runPerFileEmitting(multiFiles, "Exports", (file) => runExports({ ...opts, file }));
+  const confined = fileConfinementRefusal("This file", opts.file, opts.projectRoot);
+  if (confined !== null) {
+    emitErr(confined);
+    return 1;
+  }
+  const diskPath = resolveAgainstProjectRoot(opts.file, opts.projectRoot);
+  const symbols = querySymbols({ filePath: resolveSpecPath(diskPath), limit: -1 });
+  const kindOf = (name) => symbols.find((s) => s.name === name)?.kind ?? "export";
+  const locOf = (name) => {
+    const s = symbols.find((sym) => sym.name === name);
+    return s === void 0 ? null : { lineStart: s.lineStart, lineEnd: s.lineEnd };
+  };
+  const names = [];
+  for (const s of symbols) {
+    if (/^(?:export|pub\b|public\b)/.test(s.body.trimStart()) && !names.includes(s.name)) {
+      names.push(s.name);
+    }
+  }
+  const ext = path.extname(opts.file).toLowerCase();
+  const text = readFileText(diskPath);
+  if (text === null && symbols.length === 0) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  if (text !== null) {
+    if (ext === ".go") {
+      for (const s of symbols) if (/^[A-Z]/.test(s.name) && !names.includes(s.name)) names.push(s.name);
+    }
+    for (const n of extractExportNames(text, ext)) if (!names.includes(n)) names.push(n);
+  }
+  if (names.length === 0) {
+    emit(`No exported symbols found in '${displaySafeText(opts.file)}'`);
+    return 0;
+  }
+  const preFilterCount = names.length;
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  const filteredNames = matchesGrep !== void 0 ? names.filter((n) => matchesGrep(n)) : names;
+  const fullSourceBytes = sumFileSizes([diskPath]);
+  if (filteredNames.length === 0) {
+    if (opts.json === true) {
+      const jsonText = displaySafeJson([]);
+      emit(jsonText);
+      recordReadStat("exports", fullSourceBytes, jsonText, opts.file);
+      return 0;
+    }
+    const textOut = grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "exported symbol", "exported symbols");
+    emit(textOut);
+    recordReadStat("exports", fullSourceBytes, textOut, opts.file);
+    return 0;
+  }
+  if (opts.json === true) {
+    const jsonText = displaySafeJson(
+      filteredNames.map((n) => {
+        const loc = locOf(n);
+        return { name: n, kind: kindOf(n), lineStart: loc?.lineStart ?? null, lineEnd: loc?.lineEnd ?? null };
+      })
+    );
+    emit(jsonText);
+    recordReadStat("exports", fullSourceBytes, jsonText, opts.file);
+    return 0;
+  }
+  const outLines = filteredNames.map((n) => {
+    const loc = locOf(n);
+    const locSuffix = loc === null ? "" : ` (${loc.lineStart}-${loc.lineEnd})`;
+    return `${kindOf(n).padEnd(10)} ${n}${locSuffix}`;
+  });
+  for (const line of outLines) {
+    emit(line);
+  }
+  recordReadStat("exports", fullSourceBytes, outLines.join("\n"), opts.file);
+  return 0;
+}
+function runImports(opts) {
+  const multiFiles = opts.file.split(",").map((f) => f.trim()).filter(Boolean);
+  if (multiFiles.length > 1) return runPerFileEmitting(multiFiles, "Imports", (file) => runImports({ ...opts, file }));
+  const diskPath = resolveAgainstProjectRoot(opts.file, opts.projectRoot);
+  const text = readFileText(diskPath);
+  if (text === null) {
+    emitErr(`Could not read: ${opts.file}`);
+    return 1;
+  }
+  const imports = extractImports(text, importsExtensionFor(opts.file));
+  if (imports.length === 0) {
+    emit(`No imports found in '${displaySafeText(opts.file)}'`);
+    return 0;
+  }
+  const preFilterCount = imports.length;
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  const filteredImports = matchesGrep !== void 0 ? imports.filter((i) => matchesGrep(i)) : imports;
+  const fullSourceBytes = sumFileSizes([diskPath]);
+  if (filteredImports.length === 0) {
+    if (opts.json === true) {
+      const jsonText = displaySafeJson({ items: [], truncated: false, totalCount: 0 });
+      emit(jsonText);
+      recordReadStat("imports", fullSourceBytes, jsonText, opts.file);
+      return 0;
+    }
+    const text2 = grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "import", "imports");
+    emit(text2);
+    recordReadStat("imports", fullSourceBytes, text2, opts.file);
+    return 0;
+  }
+  if (opts.json === true) {
+    const capped = guardJsonRows(filteredImports);
+    const jsonText = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
+    emit(jsonText);
+    recordReadStat("imports", fullSourceBytes, jsonText, opts.file);
+    return 0;
+  }
+  const outLines = filteredImports.map((imp) => `import  ${imp}`);
+  for (const line of outLines) {
+    emit(line);
+  }
+  recordReadStat("imports", fullSourceBytes, outLines.join("\n"), opts.file);
+  return 0;
+}
+function extractTranscriptText(jsonl) {
+  const collected = [];
+  for (const rawLine of jsonl.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (typeof obj !== "object" || obj === null) continue;
+    const rec = obj;
+    if (rec["type"] !== "assistant") continue;
+    const msg = rec["message"];
+    if (typeof msg !== "object" || msg === null) continue;
+    const content = msg["content"];
+    if (typeof content === "string") {
+      if (content.length > 0) collected.push(content);
+      continue;
+    }
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (typeof block !== "object" || block === null) continue;
+      const b = block;
+      if (b["type"] === "text" && typeof b["text"] === "string" && b["text"].length > 0) {
+        collected.push(b["text"]);
+      }
+    }
+  }
+  return collected.join("\n");
+}
+function runNoteGet(opts) {
+  const resolvedPath = resolveSpecPath(opts.file, opts.projectRoot ?? process.cwd());
+  healStaleIndex(resolvedPath);
+  const symbol = opts.symbol ?? WHOLE_FILE_NOTE_SYMBOL;
+  const note = getNote(resolvedPath, symbol);
+  if (note === null) {
+    const where = opts.symbol !== void 0 ? ` for symbol '${opts.symbol}'` : " (whole-file note)";
+    return { text: `No note found for '${opts.file}'${where}`, code: 1 };
+  }
+  const stale = isNoteStale(note);
+  if (opts.json === true) {
+    const payload = {
+      filePath: note.filePath,
+      symbol: note.symbol === WHOLE_FILE_NOTE_SYMBOL ? null : note.symbol,
+      content: note.content,
+      stale,
+      createdAt: note.createdAt,
+      updatedAt: note.updatedAt
+    };
+    const text2 = displaySafeJson(payload);
+    recordStat("note_read");
+    return { text: text2, code: 0 };
+  }
+  const target = note.symbol === WHOLE_FILE_NOTE_SYMBOL ? opts.file : `${opts.file}::${note.symbol}`;
+  const staleTag = stale ? " [STALE \u2014 code changed since this note was written]" : "";
+  const text = `# note \u2014 ${target}${staleTag}
+${note.content}`;
+  recordStat("note_read");
+  return { text, code: 0 };
+}
+function runNoteList(opts = {}) {
+  const withStale = listNotes().map((note) => ({ note, stale: isNoteStale(note) }));
+  const filtered = opts.staleOnly === true ? withStale.filter((n) => n.stale) : withStale;
+  if (opts.json === true) {
+    const items = filtered.map(({ note, stale }) => ({
+      filePath: note.filePath,
+      symbol: note.symbol === WHOLE_FILE_NOTE_SYMBOL ? null : note.symbol,
+      stale,
+      updatedAt: note.updatedAt
+    }));
+    recordStat("note_list");
+    return { text: displaySafeJson(items), code: 0 };
+  }
+  recordStat("note_list");
+  if (filtered.length === 0) {
+    if (opts.staleOnly === true && withStale.length > 0) {
+      const noun = withStale.length === 1 ? "note" : "notes";
+      return { text: `No stale notes (${withStale.length} ${noun} recorded, none stale).`, code: 0 };
+    }
+    return { text: opts.staleOnly === true ? "No stale notes." : "No notes recorded.", code: 0 };
+  }
+  const noteListDisplayRoot = getDisplayRoot();
+  const lines = filtered.map(({ note, stale }) => {
+    const displayFile = toDisplayPath(noteListDisplayRoot, note.filePath);
+    const target = note.symbol === WHOLE_FILE_NOTE_SYMBOL ? displayFile : `${displayFile}::${note.symbol}`;
+    return `${stale ? "[STALE] " : ""}${target}`;
+  });
+  return { text: lines.join("\n"), code: 0 };
+}
+function runFind(opts) {
+  if (opts.limit !== void 0 && opts.limit <= 0) {
+    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    return 1;
+  }
+  const rootDir = resolveProjectRoot({ project: process.cwd() });
+  const patternLower = opts.pattern.toLowerCase();
+  const matchedFiles = /* @__PURE__ */ new Set();
+  const allNames = /* @__PURE__ */ new Set();
+  forEachSymbol({ rootDir }, (s) => {
+    allNames.add(s.name);
+    if (s.name.toLowerCase().includes(patternLower)) matchedFiles.add(s.filePath);
+  });
+  let fuzzyNames = [];
+  let allFiles = [...matchedFiles].sort(compareBinary);
+  if (matchedFiles.size === 0) {
+    fuzzyNames = rankSimilarNames([...allNames], opts.pattern);
+    if (fuzzyNames.length > 0) {
+      const byName = new Map(fuzzyNames.map((n) => [n, /* @__PURE__ */ new Set()]));
+      forEachSymbol({ rootDir }, (s) => {
+        byName.get(s.name)?.add(s.filePath);
+      });
+      for (const n of fuzzyNames) for (const f of [...byName.get(n) ?? []].sort(compareBinary)) matchedFiles.add(f);
+      allFiles = [...matchedFiles];
+    }
+  }
+  const files = allFiles.slice(0, opts.limit ?? 50);
+  const limitDropped = allFiles.length - files.length;
+  const truncated = limitDropped > 0;
+  if (files.length === 0) {
+    emitErr(`No indexed files match '${opts.pattern}'`);
+    return 1;
+  }
+  if (opts.json === true) {
+    const fuzzyPayload = fuzzyNames.length > 0 ? { fuzzy: true, matchedNames: fuzzyNames } : {};
+    emit(displaySafeJson({ files, truncated, totalCount: allFiles.length, ...fuzzyPayload }));
+    return 0;
+  }
+  if (fuzzyNames.length > 0) {
+    emitErr(`No symbol name contains '${opts.pattern}'; showing files for the nearest indexed ${fuzzyNames.length === 1 ? "name" : "names"}: ${fuzzyNames.join(", ")}`);
+  }
+  for (const f of files) {
+    emit(toDisplayPath(rootDir, f));
+  }
+  if (limitDropped > 0) {
+    emitErr(`Showing ${files.length} of ${allFiles.length} matching files; rerun with --limit ${allFiles.length} to see them all`);
+  }
+  return 0;
+}
+function runLocate(opts) {
+  if (opts.limit !== void 0 && opts.limit <= 0) {
+    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    return 1;
+  }
+  const rootDir = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
+  let targetSpec = opts.spec;
+  let targetFile = opts.file;
+  if (targetSpec.includes("::")) {
+    const colonIdx = targetSpec.indexOf("::");
+    targetFile = targetSpec.slice(0, colonIdx);
+    targetSpec = targetSpec.slice(colonIdx + 2);
+  }
+  const scanOpts = {};
+  if (targetFile !== void 0) {
+    scanOpts.filePath = resolveSpecPath(targetFile, rootDir);
+    healStaleIndex(scanOpts.filePath);
+  } else {
+    scanOpts.rootDir = rootDir;
+  }
+  const limit = opts.limit ?? 25;
+  const specLower = targetSpec.toLowerCase();
+  const scan = () => {
+    const found2 = { exact: new FirstRows(limit), exactCount: 0, partial: new FirstRows(limit), partialCount: 0, names: /* @__PURE__ */ new Set(), files: /* @__PURE__ */ new Set() };
+    forEachSymbol(scanOpts, (s) => {
+      found2.names.add(s.name);
+      found2.files.add(s.filePath);
+      const nameLower = s.name.toLowerCase();
+      if (nameLower === specLower) {
+        found2.exactCount++;
+        found2.exact.offer(s);
+      } else if (nameLower.includes(specLower)) {
+        found2.partialCount++;
+        found2.partial.offer(s);
+      }
+    });
+    return found2;
+  };
+  let found = scan();
+  if (targetFile === void 0) {
+    const heal = healStaleResultFiles([...found.files]);
+    if (heal.healed) found = scan();
+  }
+  let matchCount = found.exactCount + found.partialCount;
+  let combined = [...found.exact.rows(), ...found.partial.rows()];
+  let fuzzyNames = [];
+  if (matchCount === 0) {
+    fuzzyNames = rankSimilarNames([...found.names], targetSpec);
+    if (fuzzyNames.length > 0) {
+      const byName = new Map(fuzzyNames.map((n) => [n, new FirstRows(limit)]));
+      forEachSymbol(scanOpts, (s) => {
+        const bucket = byName.get(s.name);
+        if (bucket === void 0) return;
+        matchCount++;
+        bucket.offer(s);
+      });
+      combined = fuzzyNames.flatMap((n) => byName.get(n)?.rows() ?? []);
+    }
+  }
+  const shown = sinkGoneRows(combined, (s) => s.filePath).slice(0, limit);
+  if (shown.length === 0) {
+    emitErr(`No landmark or symbol located for '${targetSpec}'`);
+    return 1;
+  }
+  warnIfFilesStale(shown.map((s) => s.filePath), "locate");
+  const hits = shown.map((s) => ({
+    filePath: toDisplayPath(rootDir, s.filePath),
+    name: s.name,
+    kind: s.kind,
+    lineStart: s.lineStart,
+    lineEnd: s.lineEnd,
+    span: `${s.lineStart}-${s.lineEnd}`,
+    ...fileIsGone(s.filePath) ? { deleted: true } : {}
+  }));
+  if (opts.json === true) {
+    emit(displaySafeJson({
+      items: hits,
+      totalCount: matchCount,
+      truncated: matchCount > limit,
+      ...fuzzyNames.length > 0 ? { fuzzy: true, matchedNames: fuzzyNames } : {}
+    }));
+    return 0;
+  }
+  if (fuzzyNames.length > 0) {
+    emitErr(`No exact landmark for '${targetSpec}'; nearest matches: ${fuzzyNames.join(", ")}`);
+  }
+  for (const hit of hits) {
+    emit(`${displaySafeText(hit.filePath)}:${hit.span} [${displaySafeText(hit.kind)}] ${displaySafeText(hit.name)}${hit.deleted === true ? `  ${DELETED_TAG}` : ""}`);
+  }
+  if (matchCount > limit) {
+    emitErr(`Showing ${limit} of ${matchCount} locations; rerun with --limit ${matchCount} to see them all`);
+  }
+  return 0;
+}
+function runListSections(opts) {
+  const sections = listSections(opts.file);
+  if (sections.length === 0) {
+    if (!fileExists(opts.file)) {
+      emitErr(`Could not read: ${opts.file}`);
+      return 1;
+    }
+    emitErr(`No sections found in '${opts.file}'`);
+    return 1;
+  }
+  const preFilterCount = sections.length;
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  const totals = /* @__PURE__ */ new Map();
+  for (const heading of sections) totals.set(heading, (totals.get(heading) ?? 0) + 1);
+  const seen = /* @__PURE__ */ new Map();
+  const labelled = sections.map((heading) => {
+    const nth = (seen.get(heading) ?? 0) + 1;
+    seen.set(heading, nth);
+    return (totals.get(heading) ?? 1) > 1 ? `${heading}#${nth}` : heading;
+  });
+  const filtered = matchesGrep !== void 0 ? labelled.filter((_, i) => matchesGrep(sections[i] ?? "")) : labelled;
+  if (filtered.length === 0) {
+    if (opts.json === true) {
+      emit(displaySafeJson({ items: [], truncated: false, totalCount: 0 }));
+      return 0;
+    }
+    emit(grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "section", "sections"));
+    return 0;
+  }
+  if (opts.json === true) {
+    const capped = guardJsonRows(filtered);
+    emit(displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount }));
+    return 0;
+  }
+  for (const heading of filtered) {
+    emit(heading);
+  }
+  return 0;
+}
+
+// src/read_outline.ts
+init_define_import_meta_env();
+var DOC_SUMMARY_MAX_CHARS = 140;
+function firstSentenceEnd(line) {
+  const MIN_SENTENCE_CHARS = 30;
+  const ABBREV = new RegExp("(?:\\b(?:e\\.g|i\\.e|vs|cf|etc|approx|al|Dr|Mr|Ms|St|Fig|No)\\.|\\b\\p{L}\\.)$", "u");
+  for (const m of line.matchAll(/[.!?](?=\s|$)/gu)) {
+    const end = m.index + 1;
+    if (end < MIN_SENTENCE_CHARS) continue;
+    const head = line.slice(0, end);
+    if (ABBREV.test(head)) continue;
+    return end;
+  }
+  return null;
+}
+function clipDocSummary(firstLine) {
+  const sentence = firstSentenceEnd(firstLine);
+  if (sentence !== null && sentence <= DOC_SUMMARY_MAX_CHARS) {
+    return sentence === firstLine.length ? firstLine : `${firstLine.slice(0, sentence)}\u2026`;
+  }
+  if (firstLine.length <= DOC_SUMMARY_MAX_CHARS) return firstLine;
+  const cut = firstLine.lastIndexOf(" ", DOC_SUMMARY_MAX_CHARS);
+  return `${firstLine.slice(0, cut > 40 ? cut : DOC_SUMMARY_MAX_CHARS).trimEnd()}\u2026`;
+}
+function filteredToEmptyNotice(preFilterCount, minLines, grep) {
+  const parts = [];
+  if (minLines !== void 0) parts.push(`--min-lines ${minLines}`);
+  if (grep !== void 0) parts.push(`--grep ${grep}`);
+  return filtersFilteredToEmptyNotice(preFilterCount, parts, "indexed symbol", "indexed symbols", "the file is indexed");
+}
+function prepareSymbolListing(file, opts) {
+  const resolved = resolveSpecPath(file, opts.projectRoot ?? process.cwd());
+  const confined = fileConfinementRefusal("This file", file, opts.projectRoot);
+  if (confined !== null) return { kind: "confined", text: confined };
+  if (opts.forceRefresh === true) {
+    indexFileSyncPinned(resolved, globalDbPath());
+    enqueueDirtyPathSafe(resolved, { alreadyResolved: true });
+  } else {
+    healStaleIndex(resolved);
+  }
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  const matches = (s) => (opts.minLines === void 0 || s.lineEnd - s.lineStart + 1 >= opts.minLines) && (matchesGrep === void 0 || matchesGrep(s.name));
+  const filtered = [];
+  let scanned = 0;
+  let matchesTruncated = false;
+  let totalLines = 0;
+  for (let offset = 0; ; offset += SKELETON_SYMBOL_CAP) {
+    const page = querySymbols({ filePath: resolved, limit: SKELETON_SYMBOL_CAP, offset });
+    if (page.length === 0) break;
+    scanned += page.length;
+    for (const s of page) {
+      if (s.lineEnd > totalLines) totalLines = s.lineEnd;
+      if (!matches(s)) continue;
+      if (filtered.length === SKELETON_SYMBOL_CAP) {
+        matchesTruncated = true;
+        break;
+      }
+      filtered.push(s);
+    }
+    if (matchesTruncated || page.length < SKELETON_SYMBOL_CAP) break;
+  }
+  if (scanned === 0) {
+    return { kind: "empty", text: noSymbolsMessage(file, resolved) };
+  }
+  const trueSymbolCount = matchesTruncated ? countSymbols({ filePath: resolved }) : void 0;
+  const symbolsTruncated = matchesTruncated;
+  const refCounts = opts.stats === true ? queryRefCounts(filtered.map((s) => s.name), globalDbPath(), resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() })) : void 0;
+  const fullSourceBytes = sumFileSizes([resolved]);
+  return { kind: "ok", resolved, displayRoot: getDisplayRoot(opts.projectRoot), filtered, preFilterCount: scanned, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount, totalLines };
+}
+function runPerFileListing(files, run, json = false) {
+  const blocks = [];
+  let anyOk = false;
+  for (const file of files) {
+    const r = run(file);
+    if (r.code === 0) anyOk = true;
+    blocks.push(r.text);
+  }
+  if (json) return mergeListingJson(files, blocks, anyOk);
+  return { text: blocks.join("\n\n"), code: anyOk ? 0 : 1 };
+}
+function mergeListingJson(files, blocks, anyOk) {
+  const items = [];
+  const errors = [];
+  let truncated = false;
+  let totalCount = 0;
+  for (const [i, block] of blocks.entries()) {
+    const file = files[i] ?? "";
+    let parsed;
+    try {
+      parsed = JSON.parse(block);
+    } catch {
+      parsed = void 0;
+    }
+    if (parsed === void 0 || !Array.isArray(parsed.items)) {
+      errors.push({ file, message: block.trim() });
+      continue;
+    }
+    items.push(...parsed.items);
+    if (parsed.truncated === true) truncated = true;
+    totalCount += parsed.totalCount ?? parsed.items.length;
+  }
+  const payload = { items, truncated, totalCount, ...errors.length > 0 ? { errors } : {} };
+  return { text: displaySafeJson(payload), code: anyOk ? 0 : 1 };
+}
+function symbolCountLabel(shown, truncated, trueCount) {
+  if (!truncated || trueCount === void 0 || trueCount <= shown) return countNoun(shown, "symbol");
+  return `${shown} of ${countNoun(trueCount, "symbol")}`;
+}
+function runSkeleton(opts) {
+  const multiFiles = parseMultiFileSpec(opts.file);
+  if (multiFiles !== null) return runPerFileListing(multiFiles, (file) => runSkeleton({ ...opts, file, includeFilePath: true }), opts.json === true);
+  const prep = prepareSymbolListing(opts.file, opts);
+  if (prep.kind === "confined" || prep.kind === "empty") {
+    return { text: prep.text, code: 1 };
+  }
+  const { resolved, displayRoot, filtered, preFilterCount, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount, totalLines } = prep;
+  if (opts.json === true) {
+    const rows = filtered.map((s) => ({
+      ...opts.includeFilePath === true ? { filePath: toDisplayPath(displayRoot, s.filePath) } : {},
+      name: s.name,
+      kind: s.kind,
+      lineStart: s.lineStart,
+      lineEnd: s.lineEnd,
+      ...refCounts !== void 0 ? { refCount: refCounts.get(s.name) ?? 0, hasDoc: hasRealDocstring(s.docstring) } : {}
+    }));
+    const capped = guardJsonRows(rows);
+    const payload = {
+      items: capped.items,
+      truncated: capped.truncated || symbolsTruncated,
+      totalCount: symbolsTruncated ? Math.max(trueSymbolCount ?? 0, capped.totalCount) : capped.totalCount,
+      ...fileIsGone(resolved) ? { deleted: true } : {}
+    };
+    const text2 = displaySafeJson(payload);
+    recordStaleServed("skeleton", indexFreshness(resolved));
+    recordReadStat("stub_view", fullSourceBytes, text2, opts.file);
+    return { text: text2, code: 0 };
+  }
+  const lines = [`# Skeleton: ${opts.file}  (${symbolCountLabel(filtered.length, symbolsTruncated, trueSymbolCount)}, ${countNoun(totalLines, "line")})`];
+  if (filtered.length === 0 && preFilterCount > 0) lines.push(filteredToEmptyNotice(preFilterCount, opts.minLines, opts.grep));
+  for (const sym of filtered) {
+    const lineStr = sym.lineStart.toString().padStart(6);
+    const statsStr = formatStatsSuffix(refCounts, sym);
+    lines.push(`  ${lineStr}  ${sym.kind.padEnd(10)}  ${sym.name}  ${firstBodyLine(sym.body)}${statsStr}`);
+  }
+  const text = guardText(staleWarning(resolved, "skeleton") + lines.join("\n"), "symbol");
+  recordReadStat("stub_view", fullSourceBytes, text, opts.file);
+  return { text, code: 0 };
+}
+function runOutline(opts) {
+  const multiFiles = parseMultiFileSpec(opts.file);
+  if (multiFiles !== null) return runPerFileListing(multiFiles, (file) => runOutline({ ...opts, file, includeFilePath: true }), opts.json === true);
+  const prep = prepareSymbolListing(opts.file, opts);
+  if (prep.kind === "confined" || prep.kind === "empty") {
+    return { text: prep.text, code: 1 };
+  }
+  const { resolved, displayRoot, filtered, preFilterCount, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount } = prep;
+  if (opts.json === true) {
+    const rows = filtered.map((s) => ({
+      ...opts.includeFilePath === true ? { filePath: toDisplayPath(displayRoot, s.filePath) } : {},
+      name: s.name,
+      kind: s.kind,
+      lineStart: s.lineStart,
+      lineEnd: s.lineEnd,
+      docstring: s.docstring,
+      parent: s.parent,
+      ...refCounts !== void 0 ? { refCount: refCounts.get(s.name) ?? 0, hasDoc: hasRealDocstring(s.docstring) } : {}
+    }));
+    const capped = guardJsonRows(rows);
+    const payload = {
+      items: capped.items,
+      truncated: capped.truncated || symbolsTruncated,
+      totalCount: symbolsTruncated ? Math.max(trueSymbolCount ?? 0, capped.totalCount) : capped.totalCount,
+      ...fileIsGone(resolved) ? { deleted: true } : {}
+    };
+    const text2 = displaySafeJson(payload);
+    recordStaleServed("outline", indexFreshness(resolved));
+    recordReadStat("outline", fullSourceBytes, text2, opts.file);
+    return { text: text2, code: 0 };
+  }
+  const lines = [`# Outline: ${opts.file}  (${symbolCountLabel(filtered.length, symbolsTruncated, trueSymbolCount)})`];
+  if (filtered.length === 0 && preFilterCount > 0) lines.push(filteredToEmptyNotice(preFilterCount, opts.minLines, opts.grep));
+  for (const sym of filtered) {
+    const rangeStr = `${sym.lineStart.toString().padStart(4)}-${sym.lineEnd.toString().padEnd(6)}`;
+    const kindStr = sym.kind.padEnd(14);
+    const bodyLen = sym.lineEnd - sym.lineStart + 1;
+    const docFirst = hasRealDocstring(sym.docstring) ? `  # ${clipDocSummary(sym.docstring.split("\n")[0] ?? "")}` : "";
+    const statsStr = formatStatsSuffix(refCounts, sym);
+    const notebookSuffix = isVirtualIndexedPath(sym.filePath) ? NOTEBOOK_CELL_LINES_SUFFIX : "";
+    lines.push(`  ${rangeStr}  ${kindStr}  ${sym.name}  (${bodyLen}\u2113)${docFirst}${statsStr}${notebookSuffix}`);
+  }
+  const text = guardText(staleWarning(resolved, "outline") + lines.join("\n"), "symbol");
+  recordReadStat("outline", fullSourceBytes, text, opts.file);
+  return { text, code: 0 };
+}
+
+// src/semantic_distances.ts
+init_define_import_meta_env();
+var MIN_QUERIES_FOR_ADVICE = 20;
+var BAND_LOW = 0.7;
+var BAND_HIGH = 0.85;
+function percentile(sorted, p) {
+  const idx = p * (sorted.length - 1);
+  const lo = Math.floor(idx);
+  const hi = Math.ceil(idx);
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * (idx - lo);
+}
+function summarizeDistances(rows, weakDistance) {
+  const distances = rows.flatMap((r) => r.closest_distance === null ? [] : [r.closest_distance]).sort((a, b) => a - b);
+  const counts = [0, 0, 0, rows.length - distances.length];
+  for (const d of distances) counts[d < BAND_LOW ? 0 : d < BAND_HIGH ? 1 : 2]++;
+  const ranges = [`< ${BAND_LOW.toFixed(2)}`, `${BAND_LOW.toFixed(2)} - ${BAND_HIGH.toFixed(2)}`, `>= ${BAND_HIGH.toFixed(2)}`, "none returned"];
+  const weak = distances.filter((d) => d > weakDistance).length;
+  return {
+    total: rows.length,
+    percentiles: distances.length === 0 ? null : { p10: percentile(distances, 0.1), p25: percentile(distances, 0.25), p50: percentile(distances, 0.5), p75: percentile(distances, 0.75), p90: percentile(distances, 0.9) },
+    bands: ranges.map((range, i) => ({ range, count: counts[i], pct: rows.length === 0 ? 0 : counts[i] / rows.length * 100 })),
+    weakShare: distances.length === 0 ? null : weak / distances.length
+  };
+}
+function formatDistanceReport(summary, thresholds, scope = "this project") {
+  const lines = [`Recorded semantic queries (${scope}): ${summary.total} queries`, `Current semantic.weak_distance: ${thresholds.weakDistance}   semantic.max_distance: ${thresholds.maxDistance}`];
+  if (summary.total < MIN_QUERIES_FOR_ADVICE) {
+    lines.push(`Only ${summary.total} recorded, which is fewer than ${MIN_QUERIES_FOR_ADVICE}: too few to judge a threshold from. Run more semantic queries and check again.`);
+    return lines.join("\n");
+  }
+  if (summary.percentiles !== null) {
+    const p = summary.percentiles;
+    lines.push(`Closest distance: p10 ${p.p10.toFixed(3)}  p25 ${p.p25.toFixed(3)}  p50 ${p.p50.toFixed(3)}  p75 ${p.p75.toFixed(3)}  p90 ${p.p90.toFixed(3)}`);
+  }
+  lines.push("Band            Queries  Share");
+  for (const b of summary.bands) lines.push(`${b.range.padEnd(15)} ${String(b.count).padStart(7)}  ${b.pct.toFixed(1)}%`);
+  if (summary.weakShare !== null) lines.push(`Labelled weak at the current weak_distance: ${(summary.weakShare * 100).toFixed(1)}% of queries that returned a match`);
+  return lines.join("\n");
+}
+function recordSemanticQuery(row) {
+  try {
+    withTelemetryWriteDb((db) => {
+      db.prepare("INSERT INTO semantic_queries (ts, project_hash, closest_distance, floor_rejected_min, weak) VALUES (?, ?, ?, ?, ?)").run(Math.floor(Date.now() / 1e3), projectHash(row.projectRoot), row.closestDistance, row.floorRejectedMin, row.weak ? 1 : 0);
+    });
+  } catch {
+  }
+}
+function runSemanticDistances(opts) {
+  const { weak_distance: weakDistance, max_distance: maxDistance } = loadConfig().semantic;
+  const db = getGlobalDb();
+  const rows = opts.all === true ? db.prepare("SELECT closest_distance FROM semantic_queries").all() : db.prepare("SELECT closest_distance FROM semantic_queries WHERE project_hash = ?").all(projectHash(resolveProjectRoot({ project: process.cwd() })));
+  const scope = opts.all === true ? "all projects" : "this project";
+  return { text: formatDistanceReport(summarizeDistances(rows, weakDistance), { weakDistance, maxDistance }, scope), code: 0 };
+}
+
+// src/read_semantic.ts
+init_define_import_meta_env();
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+
+// src/semantic_merge.ts
+init_define_import_meta_env();
+var STRUCTURAL_CHUNK_KINDS = /* @__PURE__ */ new Set(["symbol", "section"]);
+function mergeNearbyHits(hits, proximity = 20) {
+  if (hits.length <= 1) {
+    return hits;
+  }
+  const byFile = /* @__PURE__ */ new Map();
+  for (const hit of hits) {
+    const fileHits = byFile.get(hit.filePath);
+    if (fileHits) {
+      fileHits.push(hit);
+    } else {
+      byFile.set(hit.filePath, [hit]);
+    }
+  }
+  const merged = [];
+  for (const fileHits of byFile.values()) {
+    const bestFirst = fileHits.map((hit, index) => ({ hit, index })).sort((a, b) => (a.hit.adjustedDistance ?? a.hit.distance) - (b.hit.adjustedDistance ?? b.hit.distance) || a.index - b.index).map((entry) => entry.hit);
+    const claimed = /* @__PURE__ */ new Set();
+    for (const anchor of bestFirst) {
+      if (claimed.has(anchor)) continue;
+      claimed.add(anchor);
+      const members = [];
+      for (const hit of bestFirst) {
+        if (claimed.has(hit)) continue;
+        const gap = hit.startLine > anchor.endLine ? hit.startLine - anchor.endLine - 1 : anchor.startLine > hit.endLine ? anchor.startLine - hit.endLine - 1 : -1;
+        const distinctUnits = STRUCTURAL_CHUNK_KINDS.has(anchor.kind) || STRUCTURAL_CHUNK_KINDS.has(hit.kind);
+        if (gap < 0 || !distinctUnits && gap <= proximity) {
+          claimed.add(hit);
+          members.push(hit);
+        }
+      }
+      members.sort((a, b) => a.startLine - b.startLine);
+      let startLine = anchor.startLine;
+      let endLine = anchor.endLine;
+      let distance = anchor.distance;
+      let adjusted = anchor.adjustedDistance ?? anchor.distance;
+      for (const m of members) {
+        startLine = Math.min(startLine, m.startLine);
+        endLine = Math.max(endLine, m.endLine);
+        distance = Math.min(distance, m.distance);
+        adjusted = Math.min(adjusted, m.adjustedDistance ?? m.distance);
+      }
+      merged.push({
+        filePath: anchor.filePath,
+        startLine,
+        endLine,
+        kind: anchor.kind,
+        distance,
+        adjustedDistance: adjusted,
+        text: [anchor.text, ...members.map((m) => m.text)].join("\n---\n")
+      });
+    }
+  }
+  merged.sort((a, b) => (a.adjustedDistance ?? a.distance) - (b.adjustedDistance ?? b.distance));
+  return merged;
+}
+
+// src/read_semantic.ts
+function resolveEnclosingSymbol(filePath, chunkStartLine, chunkEndLine, linesOf) {
+  const symbols = querySymbols({ filePath, limit: -1 }, globalDbPath());
+  const related = (s, t) => t.lineStart >= s.lineStart && t.lineEnd <= s.lineEnd || t.lineStart <= s.lineStart && t.lineEnd >= s.lineEnd;
+  const holdsChunk = (s) => {
+    if (symbols.some((t) => t !== s && !related(s, t) && t.lineStart >= chunkStartLine && t.lineStart <= chunkEndLine)) return false;
+    if (chunkEndLine <= s.lineEnd) return true;
+    const lines = linesOf(filePath);
+    return lines === null || onlyBlankOrComment(lines.slice(s.lineEnd, chunkEndLine), commentSyntaxFor(filePath));
+  };
+  let best = null;
+  for (const s of symbols) {
+    if (s.lineStart <= chunkStartLine && chunkStartLine <= s.lineEnd) {
+      if ((best === null || s.lineEnd - s.lineStart < best.lineEnd - best.lineStart) && holdsChunk(s)) best = s;
+    }
+  }
+  return best === null ? null : { name: best.name, kind: best.kind, lineStart: best.lineStart };
+}
+function onlyBlankOrComment(lines, syntax) {
+  let inBlock = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (inBlock) {
+      if (syntax?.close !== void 0 && trimmed.includes(syntax.close)) inBlock = false;
+      continue;
+    }
+    if (trimmed === "") continue;
+    if (syntax === null) return false;
+    if (syntax.open !== void 0 && trimmed.startsWith(syntax.open)) {
+      const rest = trimmed.slice(syntax.open.length);
+      if (syntax.close === void 0 || !rest.includes(syntax.close)) inBlock = true;
+      else if (rest.slice(rest.indexOf(syntax.close) + syntax.close.length).trim() !== "") return false;
+      continue;
+    }
+    if (!syntax.line.some((p) => trimmed.startsWith(p))) return false;
+  }
+  return true;
+}
+var RRF_K = 60;
+function applyRelevanceFloor(hits, floor) {
+  const kept = [];
+  let nearestRejected = null;
+  for (const h of hits) {
+    if (h.distance <= floor) {
+      kept.push(h);
+    } else if (nearestRejected === null || h.distance < nearestRejected) {
+      nearestRejected = h.distance;
+    }
+  }
+  return { kept, nearestRejected };
+}
+function semanticDegradedFields(preflight, searchSemanticError) {
+  if (preflight.status !== "ready") {
+    return {
+      preflightStatus: preflight.status,
+      warning: preflight.summary,
+      ...preflight.actionRequired ? { actionRequired: preflight.actionRequired } : {}
+    };
+  }
+  if (searchSemanticError !== null) {
+    return { preflightStatus: "degraded", warning: `Matching on meaning failed (${searchSemanticError}); results come from keyword search alone.` };
+  }
+  return {};
+}
+async function runSemantic(query, opts) {
+  if (opts.limit !== void 0 && opts.limit <= 0) {
+    const message = `--limit must be a positive number, got: ${opts.limit}`;
+    if (opts.json === true) {
+      return { text: displaySafeJson({ error: message }), code: 1 };
+    }
+    return { text: message, code: 1 };
+  }
+  const n = opts.limit !== void 0 && Number.isFinite(opts.limit) ? opts.limit : 20;
+  if (opts.projectRoot !== void 0) {
+    if (!path2.isAbsolute(opts.projectRoot) || !fs2.existsSync(opts.projectRoot) || !fs2.statSync(opts.projectRoot).isDirectory()) {
+      const message = `token-goat: projectRoot must be an absolute, existing directory, got '${opts.projectRoot}'`;
+      if (opts.json === true) {
+        return { text: displaySafeJson({ error: message }), code: 1 };
+      }
+      return { text: message, code: 1 };
+    }
+  }
+  const projectDenial = resolveProjectConfinement(opts.projectRoot).denial;
+  if (projectDenial !== null) {
+    return { text: opts.json === true ? displaySafeJson({ error: projectDenial }) : projectDenial, code: 1 };
+  }
+  const rootDir = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
+  let projectCoverage;
+  try {
+    projectCoverage = getEmbeddingCoverage(globalDbPath(), rootDir);
+  } catch {
+  }
+  const readiness = () => {
+    const check = () => checkSemanticReadiness({
+      ...opts.warm !== void 0 ? { warm: opts.warm } : {},
+      projectRoot: rootDir,
+      ...projectCoverage !== void 0 ? { coverage: projectCoverage } : {}
+    });
+    return opts.warm === true ? withExplicitDownload(check) : check();
+  };
+  if (opts.preflight === true || opts.warm === true && query === "") {
+    const preflight2 = await readiness();
+    if (opts.json === true) {
+      return { text: displaySafeJson(preflight2), code: preflight2.status === "ready" ? 0 : 1 };
+    }
+    const lines = [
+      `Semantic embedding status: ${preflight2.status.toUpperCase()}`,
+      `  Summary: ${preflight2.summary}`,
+      `  Config (indexing.embeddings_enabled): ${preflight2.configEnabled ? "enabled" : "disabled"}`,
+      `  ONNX runtime (${preflight2.runtime}): ${preflight2.runtimeAvailable ? `available (${preflight2.runtimeVersion})` : "unavailable"}`,
+      ...preflight2.runtimeBinaryPresent === null ? [] : [`  Runtime binary (${ORT_WEB_WASM.name}, ~14 MB): ${preflight2.runtimeBinaryPresent ? "downloaded" : "not downloaded yet, fetched once on first use"}`],
+      `  Model files (~35 MB): ${preflight2.modelFilesPresent ? "present" : "missing"}`,
+      `  In-memory session: ${preflight2.modelWarmed ? "ready / warmed" : "not loaded"}`,
+      `  Project coverage: ${preflight2.embeddedFiles}/${countNoun(preflight2.indexedFiles, "file")} (${preflight2.coveragePercent}%)`
+    ];
+    if (preflight2.actionRequired) {
+      lines.push(`  Action: ${preflight2.actionRequired}`);
+    }
+    return { text: lines.join("\n"), code: preflight2.status === "ready" ? 0 : 1 };
+  }
+  const preflight = await readiness();
+  const embeddingsEnabled = loadConfig().indexing?.embeddings_enabled ?? true;
+  if (embeddingsEnabled && !isAvailable()) {
+    console.warn(
+      `Matching on meaning is off (${embeddingBackendLoadError()?.message ?? "the inference runtime could not start"}); these results come from keyword search alone. ${RUNTIME_UNAVAILABLE_ADVICE}`
+    );
+  } else if (!embeddingsEnabled) {
+    console.warn(
+      "Matching on meaning is off (indexing.embeddings_enabled / TOKEN_GOAT_EMBEDDINGS_ENABLED is disabled); these results come from keyword search alone."
+    );
+  } else if (preflight.status !== "ready") {
+    console.warn(
+      `Matching on meaning is degraded (${preflight.summary}); these results come from keyword search alone.${preflight.actionRequired ? ` Action: ${preflight.actionRequired}` : ""}`
+    );
+  }
+  const overFetchForMerge = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
+  let rawHits = [];
+  let searchSemanticError = null;
+  const deferred = embeddingsEnabled && foregroundDownloadDeferred();
+  if (deferred && !modelDownloadHeld()) {
+    ensureWorkerAlive();
+    console.warn(`The embedding model is not downloaded yet. This process would go around the proxy in HTTPS_PROXY to fetch it, so the background worker downloads it through the proxy instead; these results come from keyword search alone until then. To download it now, run \`${WARM_COMMAND}\`.`);
+  }
+  if (embeddingsEnabled && !deferred) {
+    try {
+      rawHits = await searchSemantic(
+        getDb(globalDbPath()),
+        query,
+        overFetchForMerge,
+        void 0,
+        void 0,
+        rootDir
+      );
+    } catch (e) {
+      searchSemanticError = extractErrorMessage(e);
+      if (preflight.status === "ready") {
+        console.warn(
+          `Matching on meaning is off (${searchSemanticError}); these results come from keyword search alone.`
+        );
+      }
+    }
+  }
+  let floorNearestRejected = null;
+  if (rawHits.length > 0) {
+    const floor = loadConfig().semantic.max_distance;
+    const { kept, nearestRejected } = applyRelevanceFloor(rawHits, floor);
+    floorNearestRejected = nearestRejected;
+    if (kept.length === 0 && nearestRejected !== null) {
+      console.warn(
+        `Matching on meaning found nothing within ${floor} (closest was ${nearestRejected.toFixed(3)}); these results come from keyword search alone. Raise semantic.max_distance to see weaker matches.`
+      );
+    }
+    rawHits = kept;
+  }
+  const closestDense = rawHits.reduce((best, h) => best === null || h.distance < best ? h.distance : best, null);
+  const weakDistance = loadConfig().semantic.weak_distance;
+  const weakClosestDistance = closestDense !== null && closestDense > weakDistance ? closestDense : null;
+  if (closestDense !== null || preflight.status === "ready" && !searchSemanticError) {
+    recordSemanticQuery({ projectRoot: rootDir, closestDistance: closestDense, floorRejectedMin: floorNearestRejected, weak: weakClosestDistance !== null });
+  }
+  if (rawHits.length === 0 && floorNearestRejected === null && isAvailable() && preflight.status === "ready" && !searchSemanticError) {
+    try {
+      const enabled = loadConfig().indexing.embeddings_enabled;
+      const { indexedFiles, embeddedFiles } = enabled ? getEmbeddingCoverage(globalDbPath(), rootDir) : { indexedFiles: 0, embeddedFiles: 0 };
+      if (indexedFiles > 0 && embeddedFiles < indexedFiles) {
+        console.warn(
+          `Matching on meaning found nothing, and only ${embeddedFiles} of ${indexedFiles} indexed file(s) in this project have embeddings \u2014 these results come from keyword search alone. Run 'token-goat doctor' for why.`
+        );
+      }
+    } catch {
+    }
+  }
+  const mergedHits = mergeNearbyHits(rawHits);
+  const overFetchFts = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
+  const ftsRows = searchSymbolsFts(query, overFetchFts, void 0, rootDir);
+  const fused = /* @__PURE__ */ new Map();
+  const fileLines = /* @__PURE__ */ new Map();
+  const linesOf = (p) => {
+    if (!fileLines.has(p)) {
+      const text2 = readFileText(p);
+      fileLines.set(p, text2 === null ? null : text2.split(/\r?\n/));
+    }
+    return fileLines.get(p) ?? null;
+  };
+  mergedHits.forEach((h, denseRank) => {
+    const enclosing = resolveEnclosingSymbol(h.filePath, h.startLine, h.endLine, linesOf);
+    const key = enclosing !== null ? `${h.filePath}::${enclosing.name}@${enclosing.lineStart}` : `${h.filePath}::L${h.startLine}`;
+    if (fused.has(key)) return;
+    fused.set(key, {
+      filePath: h.filePath,
+      startLine: h.startLine,
+      endLine: h.endLine,
+      name: enclosing?.name ?? null,
+      kind: enclosing?.kind ?? null,
+      distance: h.distance,
+      previewText: h.text,
+      rrf: 1 / (RRF_K + denseRank),
+      inDense: true,
+      inLexical: false
+    });
+  });
+  ftsRows.forEach((s, ftsRank) => {
+    const key = `${s.filePath}::${s.name}@${s.lineStart}`;
+    const existing = fused.get(key);
+    if (existing !== void 0) {
+      existing.rrf += 1 / (RRF_K + ftsRank);
+      existing.inLexical = true;
+    } else {
+      fused.set(key, {
+        filePath: s.filePath,
+        startLine: s.lineStart,
+        endLine: s.lineEnd,
+        name: s.name,
+        kind: s.kind,
+        distance: null,
+        previewText: s.body,
+        rrf: 1 / (RRF_K + ftsRank),
+        inDense: false,
+        inLexical: true
+      });
+    }
+  });
+  const fusedHits = Array.from(fused.values()).sort((a, b) => b.rrf - a.rrf);
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  const preFilterCount = fusedHits.length;
+  const keepHit = (h) => {
+    if (opts.excludeTests === true && isTestFile(h.filePath)) return false;
+    return matchesGrep === void 0 || matchesGrep(toDisplayPath(rootDir, h.filePath));
+  };
+  const anyFilter = matchesGrep !== void 0 || opts.excludeTests === true;
+  const filteredHits = anyFilter ? fusedHits.filter(keepHit) : fusedHits;
+  const suppressedTotal = opts.excludeTests === true ? fusedHits.filter((h) => (matchesGrep === void 0 || matchesGrep(toDisplayPath(rootDir, h.filePath))) && isTestFile(h.filePath)).length : 0;
+  const eligibleCount = filteredHits.length;
+  const hits = filteredHits.slice(0, n);
+  const candidatesClipped = rawHits.length >= overFetchForMerge || ftsRows.length >= overFetchFts;
+  const hadDense = mergedHits.length > 0;
+  const hadFts = ftsRows.length > 0;
+  const source = hadDense && hadFts ? "hybrid" : hadDense ? "embeddings" : "fts";
+  warnIfFilesStale(hits.map((h) => h.filePath), "semantic");
+  if (hits.length > 0) {
+    if (opts.json === true) {
+      const items = hits.map((h, i) => ({
+        filePath: toDisplayPath(rootDir, h.filePath),
+        name: h.name,
+        kind: h.kind,
+        startLine: h.startLine,
+        endLine: h.endLine,
+        rank: i + 1,
+        rrf: h.rrf,
+        retrieval: h.inDense && h.inLexical ? "both" : h.inDense ? "dense" : "lexical",
+        distance: h.distance,
+        preview: previewLines(h.previewText, 3)
+      }));
+      const capped = guardJsonRows(items);
+      const limitTruncated = hits.length < eligibleCount;
+      const text3 = displaySafeJson({
+        source,
+        ...capped,
+        truncated: capped.truncated || limitTruncated,
+        totalCount: eligibleCount,
+        ...candidatesClipped ? { totalCountIsFloor: true } : {},
+        ...weakClosestDistance !== null ? { lowConfidence: { closestDistance: weakClosestDistance, threshold: weakDistance } } : {},
+        ...semanticDegradedFields(preflight, searchSemanticError)
+      });
+      recordReadStat("semantic_search", largestFileSize(hits.map((h) => h.filePath)), text3, query);
+      return { text: text3, code: 0 };
+    }
+    const blocks = hits.map((h, i) => {
+      const mark = h.inDense && h.inLexical ? ", +keyword" : "";
+      if (h.distance !== null) {
+        const suffix = h.name !== null ? ` \u2014 inside ${h.name} (${h.kind})` : "";
+        return `# ${i + 1}. ${toDisplayPath(rootDir, h.filePath)}:${h.startLine}-${h.endLine} (distance ${h.distance.toFixed(3)}${mark})${suffix}
+${previewLines(h.previewText, 3)}`;
+      }
+      return `# ${i + 1}. ${h.name} (${h.kind}) \u2014 ${toDisplayPath(rootDir, h.filePath)}:${h.startLine}-${h.endLine} (keyword)
+${previewLines(h.previewText, 3)}`;
+    });
+    const text2 = guardText(blocks.join("\n\n"), "semantic");
+    if (hits.length < eligibleCount) {
+      emitErr(`Showing ${hits.length} of ${candidatesClipped ? "at least " : ""}${countNoun(eligibleCount, "match", "matches")} (raise --limit to see the rest).`);
+    }
+    if (weakClosestDistance !== null) {
+      console.warn(
+        `Matching on meaning found nothing close for '${query}' (closest was ${weakClosestDistance.toFixed(3)}, weak above ${weakDistance}); these results may be unrelated. For a known name try token-goat symbol --grep <pattern> or rg, or rephrase the query.`
+      );
+    }
+    recordReadStat("semantic_search", largestFileSize(hits.map((h) => h.filePath)), text2, query);
+    return { text: text2, code: 0 };
+  }
+  if (matchesGrep !== void 0 && preFilterCount > 0) {
+    const notice = grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "match", "matches");
+    if (opts.json === true) {
+      const payload = { source: "fts", items: [], truncated: false, totalCount: 0, grepFilteredToEmpty: true, hint: notice.trim() };
+      return { text: displaySafeJson(payload), code: 0 };
+    }
+    return { text: `token-goat: ${notice.trim()}`, code: 0 };
+  }
+  if (opts.excludeTests === true && suppressedTotal > 0) {
+    const notice = `no non-test matches for '${query}' (${excludeTestsHiddenNote(suppressedTotal)})`;
+    if (opts.json === true) {
+      const payload = { source: "fts", items: [], truncated: false, totalCount: 0, excludeTestsFilteredToEmpty: true, hint: notice };
+      return { text: displaySafeJson(payload), code: 0 };
+    }
+    return { text: `token-goat: ${notice}`, code: 0 };
+  }
+  if (!anyFilter) {
+    const evidenceHits = await searchEvidenceSemantically(rootDir, query, n);
+    if (evidenceHits.length > 0) {
+      const evidenceFullBytes = evidenceHits.reduce((sum, entry) => sum + deliveredOutputBytes(Buffer.byteLength(entry.text, "utf8")), 0);
+      if (opts.json === true) {
+        const items = evidenceHits.map((entry) => ({
+          source: toDisplayPath(rootDir, entry.source),
+          representation: entry.representation,
+          preview: previewLines(entry.text, 3),
+          cachedAt: entry.createdAt
+        }));
+        const capped = guardJsonRows(items);
+        const text3 = displaySafeJson({ source: "workspace-evidence", ...capped });
+        recordReadStat("semantic_search", evidenceFullBytes, text3, query);
+        return { text: text3, code: 0 };
+      }
+      const text2 = guardText(
+        evidenceHits.map((entry) => `# cached ${entry.representation} evidence \u2014 ${toDisplayPath(rootDir, entry.source)}
+${previewLines(entry.text, 3)}`).join("\n\n"),
+        "semantic"
+      );
+      recordReadStat("semantic_search", evidenceFullBytes, text2, query);
+      return { text: text2, code: 0 };
+    }
+  }
+  const indexEmpty = isIndexEmptyForProject(globalDbPath(), rootDir);
+  if (opts.json === true) {
+    let symFound = false;
+    const trimmedQuery2 = query.trim();
+    const isIdentifier2 = /^[A-Za-z0-9_.:-]+$/.test(trimmedQuery2);
+    if (!indexEmpty && isIdentifier2) {
+      try {
+        const symMatches = querySymbols({ name: trimmedQuery2, rootDir, limit: 1 });
+        if (symMatches.length > 0) {
+          symFound = true;
+        }
+      } catch {
+      }
+    }
+    const payload = indexEmpty ? {
+      source: "fts",
+      items: [],
+      truncated: false,
+      totalCount: 0,
+      indexEmpty: true,
+      hint: emptyIndexMessage(rootDir),
+      ...semanticDegradedFields(preflight, searchSemanticError)
+    } : {
+      source: "fts",
+      items: [],
+      truncated: false,
+      totalCount: 0,
+      ...semanticDegradedFields(preflight, searchSemanticError),
+      ...!indexEmpty && isIdentifier2 ? {
+        symbolSuggestion: `token-goat symbol "${trimmedQuery2}"`,
+        ...symFound ? { indexedSymbolFound: true } : {}
+      } : {}
+    };
+    const text2 = displaySafeJson(payload);
+    return { text: text2, code: 1 };
+  }
+  let text = indexEmpty ? `token-goat: no matches for '${query}'
+${emptyIndexMessage(rootDir)}` : `token-goat: no matches for '${query}'`;
+  const trimmedQuery = query.trim();
+  const isIdentifier = /^[A-Za-z0-9_.:-]+$/.test(trimmedQuery);
+  if (!indexEmpty && isIdentifier) {
+    let symFound = false;
+    try {
+      const symMatches = querySymbols({ name: trimmedQuery, rootDir, limit: 1 });
+      if (symMatches.length > 0) {
+        symFound = true;
+      }
+    } catch {
+    }
+    if (symFound) {
+      text += `
+(note: '${trimmedQuery}' is an indexed symbol name; use: token-goat symbol "${trimmedQuery}")`;
+    } else {
+      text += `
+Try: token-goat symbol "${trimmedQuery}"`;
+    }
+  }
+  if (preflight.status !== "ready") {
+    text += `
+(note: semantic indexing is degraded [${preflight.status}]: ${preflight.summary}${preflight.actionRequired ? ` \u2014 ${preflight.actionRequired}` : ""})`;
+  } else if (searchSemanticError !== null) {
+    text += `
+(note: semantic matching degraded: ${searchSemanticError}; results come from keyword search alone)`;
+  }
+  return { text, code: 1 };
+}
+async function runSemanticMulti(queries, opts) {
+  const laterOpts = { ...opts };
+  delete laterOpts.warm;
+  const blocks = [];
+  const entries = [];
+  let anyOk = false;
+  for (const [i, query] of queries.entries()) {
+    const sub = await runSemantic(query, i === 0 ? opts : laterOpts);
+    if (sub.code === 0) anyOk = true;
+    if (opts.json === true) {
+      entries.push({ query, ...JSON.parse(sub.text) });
+      continue;
+    }
+    blocks.push(`'${query}':
+${sub.text}`);
+  }
+  return { text: opts.json === true ? displaySafeJson(entries) : blocks.join("\n\n"), code: anyOk ? 0 : 1 };
+}
+
+// src/read_refs.ts
+init_define_import_meta_env();
+function refsDisplayPath(p) {
+  return toDisplayPath(getDisplayRoot(), p);
+}
+function goneSuffix(filePath) {
+  return fileIsGone(filePath) ? `  ${DELETED_TAG}` : "";
+}
+function refGrepFilter(grep) {
+  if (grep === void 0) return void 0;
+  const matches = compileGrepMatcher(grep);
+  return (r) => matches(refsDisplayPath(r.filePath));
+}
+function refsJsonItems(items, contextLines) {
+  return withContextLines(items, contextLines).map((r) => ({ ...r, filePath: refsDisplayPath(r.filePath), ...fileIsGone(r.filePath) ? { deleted: true } : {} }));
+}
+function renderRefLines(ref, contextLines, indent = "  ") {
+  const displayPath = refsDisplayPath(ref.filePath);
+  const base = `${indent}${displaySafeText(displayPath)}:${ref.line}: ${displaySafeText(ref.context)}${goneSuffix(ref.filePath)}`;
+  const window = buildContextWindow(ref.filePath, ref.line, contextLines);
+  if (window === null) return [base];
+  return [base, ...renderContextWindow(displayPath, ref.line, window, "", `${indent}  `)];
+}
+function withContextLines(items, contextLines) {
+  if (!(contextLines > 0)) return items;
+  return items.map((r) => ({ ...r, contextLines: buildContextWindow(r.filePath, r.line, contextLines) ?? [] }));
+}
+function applyTypedRefsTier(symName, file, results, qualifiedDef) {
+  if (results.length === 0) return results;
+  try {
+    const symbolQueryOpts = { name: symName, limit: 2 };
+    if (file !== void 0) symbolQueryOpts.filePath = file;
+    const defs = qualifiedDef !== void 0 ? [qualifiedDef] : querySymbols(symbolQueryOpts);
+    if (defs.length !== 1) return results;
+    return typedRefsForDef(results, defs[0]) ?? results;
+  } catch {
+    return results;
+  }
+}
+function parseMultiRefsSpec(spec) {
+  const colonIdx = findSpecSeparator(spec);
+  const file = colonIdx === -1 ? void 0 : spec.slice(0, colonIdx);
+  const symPart = colonIdx === -1 ? spec : spec.slice(colonIdx + 2);
+  const symbols = symPart.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return { file, symbols };
+}
+function refsRootDir(opts) {
+  return opts.projectRoot ?? confinedProjectRoot() ?? void 0;
+}
+function refsSpecFiles(spec) {
+  const crossFile = parseCrossFileMultiSpec(spec);
+  if (crossFile !== null) return [...new Set(crossFile.map((p) => p.file))];
+  const { file } = parseMultiRefsSpec(spec);
+  return file === void 0 ? [] : [file];
+}
+function collectRefs(requestedName, defFile, opts, resolvedDef) {
+  const qualifiedDef = resolvedDef ?? (defFile !== void 0 && requestedName.includes(".") ? resolveQualifiedSpecDef(`${defFile}::${requestedName}`, opts.projectRoot ?? process.cwd()) : void 0);
+  const symName = qualifiedDef?.name ?? requestedName;
+  const queryOpts = { name: symName };
+  const defFileHint = defFile !== void 0 ? resolveSpecPath(defFile, opts.projectRoot ?? process.cwd()) : void 0;
+  if (opts.excludeTests === true || opts.grep !== void 0) queryOpts.limit = UNBOUNDED_QUERY_LIMIT;
+  else if (opts.limit !== void 0) queryOpts.limit = opts.limit;
+  else if (opts.top !== void 0) queryOpts.limit = UNBOUNDED_QUERY_LIMIT;
+  const rootDir = refsRootDir(opts);
+  if (rootDir !== void 0) queryOpts.rootDir = rootDir;
+  if (defFileHint !== void 0 && !fileIsGone(defFileHint)) healStaleIndex(defFileHint);
+  let scanned = queryRefs(queryOpts);
+  if (healStaleResultFiles(scanned.map((r) => r.filePath)).healed) scanned = queryRefs(queryOpts);
+  const preScanCount = scanned.length;
+  const scanLimit = queryOpts.limit ?? DEFAULT_QUERY_LIMIT;
+  let results = applyTypedRefsTier(symName, defFileHint, scanned, qualifiedDef);
+  const typedFilterDropped = results.length < scanned.length;
+  let suppressed = 0;
+  if (opts.excludeTests === true) {
+    const f = applyExcludeTestsFilter(results);
+    suppressed = f.suppressed;
+    results = f.refs;
+  }
+  const preGrepCount = results.length;
+  const matchesGrep = refGrepFilter(opts.grep);
+  if (matchesGrep !== void 0) results = results.filter(matchesGrep);
+  const clientFiltered = opts.excludeTests === true || matchesGrep !== void 0 || typedFilterDropped;
+  const filteredTotal = clientFiltered ? results.length : void 0;
+  results = sinkGoneRows(results, (r) => r.filePath);
+  if (clientFiltered && opts.top === void 0) results = results.slice(0, opts.limit ?? 100);
+  return { queryOpts, defFileHint, results, preScanCount, scanLimit, suppressed, preGrepCount, clientFiltered, filteredTotal };
+}
+function refsTotal(clientFiltered, filteredTotal, shown, countExact, preScanCount, scanLimit) {
+  if (!clientFiltered) return { count: countExact(), exact: true };
+  if (scanLimit < 0) return { count: filteredTotal ?? shown, exact: true };
+  return { count: filteredTotal ?? shown, exact: preScanCount < scanLimit };
+}
+function refsSearchBaselineBytes(rows) {
+  let total = 0;
+  for (const ref of rows) total += Buffer.byteLength(`${refsDisplayPath(ref.filePath)}:${ref.line}: ${ref.context}
+`, "utf8");
+  return deliveredOutputBytes(total);
+}
+function renderRefsTargets(targets, opts, {
+  annotateHiddenByGrep
+}) {
+  for (const { file, symbol } of targets) {
+    if (file === void 0 || !symbol.includes(".")) continue;
+    const qualified = resolveQualifiedSpec(`${file}::${symbol}`, opts.projectRoot ?? process.cwd());
+    if (qualified?.kind !== "ambiguous") continue;
+    emitErr(formatAmbiguity(qualified.symbol, qualified.file, qualified.candidates, opts.projectRoot, "refs"));
+    return 1;
+  }
+  const jsonOut = {};
+  let anyFound = false;
+  const lines = [];
+  const refRows = [];
+  for (const { file, symbol, key } of targets) {
+    const { queryOpts, results, preScanCount, scanLimit, suppressed, preGrepCount, clientFiltered, filteredTotal } = collectRefs(symbol, file, opts);
+    if (results.length > 0) anyFound = true;
+    refRows.push(...results);
+    if (opts.json === true) {
+      const hiddenByGrep = opts.grep !== void 0 ? preGrepCount - (filteredTotal ?? results.length) : 0;
+      const withHidden = (payload) => ({ ...payload, ...annotateHiddenByGrep && hiddenByGrep > 0 ? { hiddenByGrep } : {} });
+      if (opts.top !== void 0) {
+        jsonOut[key] = withHidden(topFilesJsonPayload(results, opts.top));
+      } else {
+        const capped = guardJsonRows(results);
+        const trueTotal = clientFiltered ? filteredTotal ?? results.length : countRefs(queryOpts);
+        jsonOut[key] = withHidden({ items: refsJsonItems(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal });
+      }
+      continue;
+    }
+    if (results.length === 0) {
+      if (opts.grep !== void 0 && preGrepCount > 0) {
+        lines.push(`${key}: ${grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references").trim()}`);
+        continue;
+      }
+      lines.push(opts.excludeTests === true && suppressed > 0 ? `${key}: (no non-test references found; ${excludeTestsHiddenNote(suppressed)})` : `${key}: (no references found)`);
+      continue;
+    }
+    lines.push(`${key}:`);
+    if (opts.top !== void 0) {
+      lines.push(...renderTopFilesSummary(results, opts.top, suppressed));
+    } else if (opts.callers === true) {
+      if (opts.excludeTests === true && suppressed > 0) lines.push(`  ${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`);
+      lines.push(...renderCallerGroups(results, opts.context ?? 0));
+    } else {
+      if (opts.excludeTests === true && suppressed > 0) lines.push(`  ${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`);
+      for (const ref of results) lines.push(...renderRefLines(ref, opts.context ?? 0));
+    }
+    if (opts.top === void 0) {
+      const notice = truncationNotice(
+        results.length,
+        opts.limit ?? 100,
+        () => refsTotal(clientFiltered, filteredTotal, results.length, () => countRefs(queryOpts), preScanCount, scanLimit),
+        "references",
+        "--limit"
+      );
+      if (notice !== null) lines.push(`  token-goat: ${notice}`);
+    }
+  }
+  warnIfFilesStale(refRows.map((r) => r.filePath), "refs");
+  const fullSourceBytes = refsSearchBaselineBytes(refRows);
+  if (opts.json === true) {
+    const text2 = displaySafeJson(jsonOut);
+    emit(text2);
+    if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text2, opts.spec);
+    return anyFound ? 0 : 1;
+  }
+  const text = lines.join("\n");
+  emitGuarded(text, "symbol");
+  if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text, opts.spec);
+  return anyFound ? 0 : 1;
+}
+function runRefs(opts) {
+  if (opts.limit !== void 0 && opts.limit <= 0) {
+    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    return 1;
+  }
+  if (opts.top !== void 0 && opts.top <= 0) {
+    emitErr(`--top must be a positive number, got: ${opts.top}`);
+    return 1;
+  }
+  const { root: confinedRoot, denial: projectDenial } = resolveProjectConfinement(opts.projectRoot);
+  if (projectDenial !== null) {
+    emitErr(projectDenial);
+    return 1;
+  }
+  if (confinedRoot !== null) {
+    for (const file2 of refsSpecFiles(opts.spec)) {
+      const denial = confinementRefusal("This file", resolveSpecPath(file2, opts.projectRoot ?? process.cwd()), confinedRoot);
+      if (denial !== null) {
+        emitErr(denial);
+        return 1;
+      }
+    }
+  }
+  const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
+  if (crossFilePairs !== null) return runRefsCrossFile(crossFilePairs, opts);
+  const { file, symbols } = parseMultiRefsSpec(opts.spec);
+  if (symbols.length <= 1) return runRefsSingle(opts);
+  return renderRefsTargets(
+    symbols.map((symbol) => ({ file, symbol, key: symbol })),
+    opts,
+    { annotateHiddenByGrep: true }
+  );
+}
+function runRefsCrossFile(pairs, opts) {
+  const distinctFiles = new Set(pairs.map((p) => p.file));
+  const keyFor = (p) => distinctFiles.size === 1 ? p.symbol : `${p.file}::${p.symbol}`;
+  return renderRefsTargets(
+    pairs.map((p) => ({ file: p.file, symbol: p.symbol, key: keyFor(p) })),
+    opts,
+    // Not annotated today; renderRefsTargets's own option doc explains why that is a preserved divergence rather than a decision.
+    { annotateHiddenByGrep: false }
+  );
+}
+function runRefsSingle(opts) {
+  const { file, symbol } = parseReadSpec(opts.spec);
+  const qualified = resolveQualifiedSpec(opts.spec, opts.projectRoot ?? process.cwd());
+  if (qualified?.kind === "ambiguous") {
+    emitErr(formatAmbiguity(qualified.symbol, qualified.file, qualified.candidates, opts.projectRoot, "refs"));
+    return 1;
+  }
+  const qualifiedDef = qualified?.kind === "ok" ? qualified.entry : void 0;
+  const symName = qualifiedDef?.name ?? symbol ?? file;
+  const { queryOpts, defFileHint, results, preScanCount, scanLimit, suppressed, preGrepCount, clientFiltered, filteredTotal } = collectRefs(symName, symbol !== void 0 ? file : void 0, opts, qualifiedDef);
+  if (results.length === 0) {
+    if (opts.grep !== void 0 && preGrepCount > 0) {
+      if (opts.json === true) {
+        emit(displaySafeJson({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preGrepCount }));
+        return 0;
+      }
+      emit(grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references"));
+      return 0;
+    }
+    if (opts.excludeTests === true && suppressed > 0) {
+      emitErr(`No non-test references found for '${symName}' (${excludeTestsHiddenNote(suppressed)})`);
+      return 1;
+    }
+    const rootDir = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
+    const defRows = querySymbols({ name: symName, rootDir, limit: REF_BLIND_DEF_PROBE_LIMIT });
+    if (defRows.length === 0) {
+      emitErr(`Symbol not found: ${symName}${unknownSymbolSuggestion(symName, rootDir)}`);
+      if (opts.json !== true && isIndexEmptyForProject(globalDbPath(), rootDir)) emitErr(emptyIndexMessage(rootDir));
+      return 1;
+    }
+    const defPaths = defFileHint !== void 0 ? [defFileHint] : defRows.map((r) => r.filePath);
+    const firstDefPath = defPaths[0];
+    if (firstDefPath !== void 0 && defPaths.every((fp) => !isRefIndexedFile(fp))) {
+      emitErr(refBlindLanguageNotice(symName, detectLanguageOfFile(firstDefPath), refsDisplayPath(firstDefPath)));
+      return 1;
+    }
+    const kindRows = defFileHint !== void 0 ? querySymbols({ name: symName, filePath: defFileHint, rootDir, limit: REF_BLIND_DEF_PROBE_LIMIT }) : defRows;
+    const kindVerdict = refBlindKindVerdict(kindRows);
+    if (kindVerdict.allBlind) {
+      emitErr(refBlindKindNotice(symName, kindVerdict.blindKinds));
+      return 1;
+    }
+    emitErr(`No references found for '${symName}'`);
+    if (kindVerdict.blindCount > 0) emitErr(refBlindKindPartialNote(symName, kindVerdict.blindKinds, kindVerdict.blindCount, kindRows.length));
+    if (opts.json !== true) {
+      if (isIndexEmptyForProject(globalDbPath(), rootDir)) emitErr(emptyIndexMessage(rootDir));
+    }
+    return 1;
+  }
+  warnIfFilesStale(results.map((r) => r.filePath), "refs");
+  const fullSourceBytes = refsSearchBaselineBytes(results);
+  if (opts.json === true) {
+    let payload;
+    if (opts.top !== void 0) {
+      payload = topFilesJsonPayload(results, opts.top);
+    } else {
+      const capped = guardJsonRows(results);
+      const trueTotal = clientFiltered ? filteredTotal ?? results.length : countRefs(queryOpts);
+      payload = { items: refsJsonItems(capped.items, opts.context ?? 0), truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
+    }
+    const hiddenByGrep = opts.grep !== void 0 ? preGrepCount - (filteredTotal ?? results.length) : 0;
+    const text2 = displaySafeJson({ ...payload, ...hiddenByGrep > 0 ? { hiddenByGrep } : {} });
+    emit(text2);
+    recordReadStat("symbol_read", fullSourceBytes, text2, symName);
+    return 0;
+  }
+  const lines = opts.top !== void 0 ? renderTopFilesSummary(results, opts.top, suppressed) : opts.callers === true ? [...opts.excludeTests === true && suppressed > 0 ? [`${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`] : [], ...renderCallerGroups(results, opts.context ?? 0)] : [...opts.excludeTests === true && suppressed > 0 ? [`${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`] : [], ...results.flatMap((ref) => renderRefLines(ref, opts.context ?? 0, ""))];
+  const refsFooter = opts.top !== void 0 ? "" : truncationFooter(results.length, opts.limit ?? 100, () => refsTotal(clientFiltered, filteredTotal, results.length, () => countRefs(queryOpts), preScanCount, scanLimit), "references", "--limit");
+  const text = lines.join("\n");
+  emit(guardText(text, "symbol") + refsFooter);
+  recordReadStat("symbol_read", fullSourceBytes, text + refsFooter, symName);
+  return 0;
+}
+function applyExcludeTestsFilter(refs) {
+  const filtered = refs.filter((r) => !isTestFile(r.filePath));
+  return { refs: filtered, suppressed: refs.length - filtered.length };
+}
+function groupRefsByFile(refs) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const ref of refs) byFile.set(ref.filePath, (byFile.get(ref.filePath) ?? 0) + 1);
+  return [...byFile.entries()].map(([file, count]) => ({ file, count })).sort((a, b) => b.count - a.count || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+}
+function renderTopFilesSummary(refs, topN, suppressed) {
+  const grouped = groupRefsByFile(refs);
+  const shown = grouped.slice(0, topN);
+  const suppressedNote = suppressed !== void 0 && suppressed > 0 ? ` (${excludeTestsHiddenNote(suppressed)})` : "";
+  const lines = [`${countNoun(refs.length, "reference")} across ${countNoun(grouped.length, "file")} (showing top ${shown.length})${suppressedNote}`];
+  for (const { file, count } of shown) lines.push(`  ${count}  ${refsDisplayPath(file)}${goneSuffix(file)}`);
+  const omittedFiles = grouped.length - shown.length;
+  if (omittedFiles > 0) {
+    const shownRefs = shown.reduce((sum, g) => sum + g.count, 0);
+    lines.push(`  ...(${omittedFiles} more files, ${refs.length - shownRefs} more references elided; use a higher --top to see more)`);
+  }
+  return lines;
+}
+function topFilesJsonPayload(refs, topN) {
+  const grouped = groupRefsByFile(refs);
+  const shown = grouped.slice(0, topN);
+  return { fileCounts: shown.map((g) => ({ ...g, file: refsDisplayPath(g.file), ...fileIsGone(g.file) ? { deleted: true } : {} })), totalFiles: grouped.length, totalRefs: refs.length, shown: shown.length };
+}
+function renderCallerGroups(refs, contextLines = 0) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const ref of refs) {
+    const bucket = byFile.get(ref.filePath);
+    if (bucket !== void 0) {
+      bucket.push(ref);
+    } else {
+      byFile.set(ref.filePath, [ref]);
+    }
+  }
+  const lines = [];
+  for (const [file, fileRefs] of byFile) {
+    const displayPath = refsDisplayPath(file);
+    lines.push(`${displaySafeText(displayPath)}:${goneSuffix(file)}`);
+    for (const ref of fileRefs) {
+      lines.push(`  :${ref.line}  ${ref.context !== "" ? displaySafeText(ref.context) : "(module scope)"}`);
+      const window = buildContextWindow(file, ref.line, contextLines);
+      if (window !== null) lines.push(...renderContextWindow(displayPath, ref.line, window, "", "    "));
+    }
+  }
+  return lines;
+}
+
+// src/read_git.ts
+init_define_import_meta_env();
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
+
+// src/conflict_query.ts
+init_define_import_meta_env();
+var OURS_RE = /^<{7}(?:\s+(.*))?$/;
+var BASE_RE = /^\|{7}(?:\s+(.*))?$/;
+var SEP_RE = /^={7}\s*$/;
+var THEIRS_RE = /^>{7}(?:\s+(.*))?$/;
+function parseConflicts(filePath, text, contextLines = 3) {
+  const lines = text.split(/\r?\n/);
+  const regions = [];
+  const warnings = [];
+  let state = "none";
+  let startLine = 0;
+  let oursLabel = "";
+  let oursLines = [];
+  let baseLabel = "";
+  let baseLines = [];
+  let sawBase = false;
+  let theirsLines = [];
+  const resetRegion = () => {
+    state = "none";
+    oursLabel = "";
+    oursLines = [];
+    baseLabel = "";
+    baseLines = [];
+    sawBase = false;
+    theirsLines = [];
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const lineNo = i + 1;
+    const oursMatch = OURS_RE.exec(line);
+    if (oursMatch !== null) {
+      if (state !== "none") {
+        warnings.push({
+          filePath,
+          line: startLine,
+          message: `Unterminated conflict marker starting at line ${startLine} -- found a new '<<<<<<<' at line ${lineNo} before a matching '=======' / '>>>>>>>'`
+        });
+      }
+      startLine = lineNo;
+      oursLabel = (oursMatch[1] ?? "").trim();
+      oursLines = [];
+      baseLabel = "";
+      baseLines = [];
+      sawBase = false;
+      theirsLines = [];
+      state = "ours";
+      continue;
+    }
+    if (state === "none") continue;
+    if (state === "ours") {
+      const baseMatch = BASE_RE.exec(line);
+      if (baseMatch !== null) {
+        baseLabel = (baseMatch[1] ?? "").trim();
+        baseLines = [];
+        sawBase = true;
+        state = "base";
+        continue;
+      }
+    }
+    if ((state === "ours" || state === "base") && SEP_RE.test(line)) {
+      theirsLines = [];
+      state = "theirs";
+      continue;
+    }
+    if (state === "theirs") {
+      const theirsMatch = THEIRS_RE.exec(line);
+      if (theirsMatch !== null) {
+        const theirsLabel = (theirsMatch[1] ?? "").trim();
+        const beforeContext = [];
+        if (contextLines > 0) {
+          const ctxStart = Math.max(0, startLine - 1 - contextLines);
+          for (let c = ctxStart; c < startLine - 1; c++) {
+            beforeContext.push({ line: c + 1, text: lines[c] ?? "" });
+          }
+        }
+        const afterContext = [];
+        if (contextLines > 0) {
+          const ctxEnd = Math.min(lines.length, lineNo + contextLines);
+          for (let c = lineNo; c < ctxEnd; c++) {
+            afterContext.push({ line: c + 1, text: lines[c] ?? "" });
+          }
+        }
+        regions.push({
+          filePath,
+          lineStart: startLine,
+          lineEnd: lineNo,
+          ours: { label: oursLabel, content: oursLines.join("\n") },
+          base: sawBase ? { label: baseLabel, content: baseLines.join("\n") } : null,
+          theirs: { label: theirsLabel, content: theirsLines.join("\n") },
+          ...beforeContext.length > 0 ? { beforeContext } : {},
+          ...afterContext.length > 0 ? { afterContext } : {}
+        });
+        resetRegion();
+        continue;
+      }
+    }
+    if (state === "ours") oursLines.push(line);
+    else if (state === "base") baseLines.push(line);
+    else if (state === "theirs") theirsLines.push(line);
+  }
+  if (state !== "none") {
+    warnings.push({
+      filePath,
+      line: startLine,
+      message: `Unterminated conflict marker starting at line ${startLine} -- reached end of file without a matching '>>>>>>>'`
+    });
+  }
+  return { filePath, regions, warnings };
+}
+function summarizeFileConflicts(result) {
+  return {
+    filePath: result.filePath,
+    conflictCount: result.regions.length,
+    regions: result.regions.map((r) => ({
+      lineStart: r.lineStart,
+      lineEnd: r.lineEnd,
+      oursLabel: r.ours.label,
+      baseLabel: r.base !== null ? r.base.label : null,
+      theirsLabel: r.theirs.label
+    })),
+    warnings: result.warnings
+  };
+}
+function indentBlock(content) {
+  if (content === "") return "";
+  return content.split("\n").map((l) => `      ${l}`).join("\n");
+}
+function formatSingleFileConflicts(result) {
+  const lines = [];
+  if (result.regions.length > 0) {
+    lines.push(`${displaySafeText(result.filePath)} -- ${result.regions.length} conflict${result.regions.length === 1 ? "" : "s"}`);
+    for (const r of result.regions) {
+      lines.push(`  lines ${r.lineStart}-${r.lineEnd}`);
+      if (r.beforeContext && r.beforeContext.length > 0) {
+        for (const c of r.beforeContext) {
+          lines.push(`      ${c.line} | ${displaySafeText(c.text)}`);
+        }
+      }
+      lines.push(`    <<<<<<< ${displaySafeText(r.ours.label || "(ours)")}`);
+      lines.push(indentBlock(r.ours.content));
+      if (r.base !== null) {
+        lines.push(`    ||||||| ${displaySafeText(r.base.label || "(base)")}`);
+        lines.push(indentBlock(r.base.content));
+      }
+      lines.push("    =======");
+      lines.push(indentBlock(r.theirs.content));
+      lines.push(`    >>>>>>> ${displaySafeText(r.theirs.label || "(theirs)")}`);
+      if (r.afterContext && r.afterContext.length > 0) {
+        for (const c of r.afterContext) {
+          lines.push(`      ${c.line} | ${displaySafeText(c.text)}`);
+        }
+      }
+    }
+  } else {
+    lines.push(`${displaySafeText(result.filePath)} -- no conflicts`);
+  }
+  if (result.warnings.length > 0) {
+    lines.push("  warnings:");
+    for (const w of result.warnings) lines.push(`    line ${w.line}: ${displaySafeText(w.message)}`);
+  }
+  return lines.join("\n");
+}
+function formatConflicts(results) {
+  const withData = results.filter((r) => r.regions.length > 0 || r.warnings.length > 0);
+  if (withData.length === 0) return "No conflicts found.";
+  return withData.map(formatSingleFileConflicts).join("\n\n");
+}
+function formatSingleFileSummary(summary) {
+  const lines = [];
+  if (summary.conflictCount > 0) {
+    lines.push(`${displaySafeText(summary.filePath)} -- ${summary.conflictCount} conflict${summary.conflictCount === 1 ? "" : "s"}`);
+    for (const r of summary.regions) {
+      const baseText = r.baseLabel !== null ? ` base=${displaySafeText(r.baseLabel || "(unlabeled)")}` : "";
+      lines.push(`  lines ${r.lineStart}-${r.lineEnd}  ours=${displaySafeText(r.oursLabel || "(unlabeled)")}${baseText} theirs=${displaySafeText(r.theirsLabel || "(unlabeled)")}`);
+    }
+  } else {
+    lines.push(`${displaySafeText(summary.filePath)} -- no conflicts`);
+  }
+  if (summary.warnings.length > 0) {
+    lines.push("  warnings:");
+    for (const w of summary.warnings) lines.push(`    line ${w.line}: ${displaySafeText(w.message)}`);
+  }
+  return lines.join("\n");
+}
+function formatConflictSummaries(summaries) {
+  const withData = summaries.filter((s) => s.conflictCount > 0 || s.warnings.length > 0);
+  if (withData.length === 0) return "No conflicts found.";
+  return withData.map(formatSingleFileSummary).join("\n");
+}
+
+// src/read_git.ts
+function runConflicts(opts) {
+  let files;
+  if (opts.path === void 0) {
+    files = walkProject(process.cwd()).files;
+  } else {
+    const abs = path3.resolve(opts.path);
+    let stat;
+    try {
+      stat = fs3.statSync(abs);
+    } catch {
+      emitErr(`Could not read: ${opts.path}`);
+      return 1;
+    }
+    files = stat.isDirectory() ? walkProject(abs).files : [abs];
+  }
+  const contextLines = opts.context !== void 0 ? opts.context : 3;
+  const results = [];
+  for (const f of files) {
+    const text = readFileText(f);
+    if (text === null) continue;
+    const parsed = parseConflicts(f, text, contextLines);
+    if (parsed.regions.length > 0 || parsed.warnings.length > 0) results.push(parsed);
+  }
+  const fullSourceBytes = sumFileSizes(files);
+  const detail = opts.path ?? ".";
+  if (opts.json === true) {
+    const jsonText = displaySafeJson(opts.summary === true ? results.map(summarizeFileConflicts) : results, 0);
+    emit(jsonText);
+    recordReadStat("conflicts", fullSourceBytes, jsonText, detail);
+  } else if (opts.summary === true) {
+    const text = formatConflictSummaries(results.map(summarizeFileConflicts));
+    emitGuarded(text, "conflicts");
+    recordReadStat("conflicts", fullSourceBytes, text, detail);
+  } else {
+    const text = formatConflicts(results);
+    emitGuarded(text, "conflicts");
+    recordReadStat("conflicts", fullSourceBytes, text, detail);
+  }
+  return 0;
+}
+var HUNK_HEADER_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+function hunkHeaderRange(m) {
+  const newStart = parseInt(m[1], 10);
+  const newLines = m[2] !== void 0 ? parseInt(m[2], 10) : 1;
+  return newLines === 0 ? { start: Math.max(newStart, 1), end: Math.max(newStart, 1) } : { start: newStart, end: newStart + newLines - 1 };
+}
+var C_ESCAPES = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, "\\": 92 };
+function unquoteGitPath(quoted) {
+  const bytes = [];
+  for (let i = 0; i < quoted.length; i++) {
+    const ch = quoted.charAt(i);
+    if (ch !== "\\") {
+      bytes.push(...Buffer.from(ch, "utf8"));
+      continue;
+    }
+    const next = quoted.charAt(i + 1);
+    const octal = /^[0-7]{3}/.exec(quoted.slice(i + 1, i + 4));
+    if (octal !== null) {
+      bytes.push(parseInt(octal[0], 8));
+      i += 3;
+    } else if (C_ESCAPES[next] !== void 0) {
+      bytes.push(C_ESCAPES[next]);
+      i += 1;
+    } else {
+      bytes.push(92);
+    }
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+function newSidePath(line) {
+  const quoted = /^\+\+\+ "b\/(.*)"$/.exec(line);
+  if (quoted !== null) return unquoteGitPath(quoted[1] ?? "");
+  const plain = /^\+\+\+ b\/(.+?)\t?$/.exec(line);
+  return plain === null ? null : plain[1] ?? null;
+}
+function parseDiffHunks(diffText) {
+  const hunksByFile = /* @__PURE__ */ new Map();
+  let currentFile = null;
+  for (const line of diffText.split(/\r?\n/)) {
+    if (line.startsWith("+++ ") && line !== "+++ /dev/null") {
+      currentFile = newSidePath(line);
+      continue;
+    }
+    if (line === "+++ /dev/null") {
+      currentFile = null;
+      continue;
+    }
+    const hunkMatch = HUNK_HEADER_RE.exec(line);
+    if (hunkMatch !== null && currentFile !== null) {
+      const range = hunkHeaderRange(hunkMatch);
+      const existing = hunksByFile.get(currentFile);
+      if (existing !== void 0) {
+        existing.push(range);
+      } else {
+        hunksByFile.set(currentFile, [range]);
+      }
+    }
+  }
+  return hunksByFile;
+}
+function parseHunklessFiles(diffText) {
+  const hunkless = /* @__PURE__ */ new Set();
+  let path5 = null;
+  let metadataOnly = false;
+  let hasContent = false;
+  const flush = () => {
+    if (path5 !== null && metadataOnly && !hasContent) hunkless.add(path5);
+  };
+  for (const line of diffText.split(/\r?\n/)) {
+    if (line.startsWith("diff --git ")) {
+      flush();
+      const header = /^diff --git "?a\/.*?"? "?b\/(.*?)"?$/.exec(line);
+      path5 = header === null ? null : line.endsWith('"') ? unquoteGitPath(header[1] ?? "") : header[1] ?? null;
+      metadataOnly = false;
+      hasContent = false;
+    } else if (line.startsWith("rename to ")) {
+      const to = line.slice("rename to ".length);
+      path5 = to.startsWith('"') && to.endsWith('"') && to.length > 1 ? unquoteGitPath(to.slice(1, -1)) : to;
+      metadataOnly = true;
+    } else if (line.startsWith("new mode ")) {
+      metadataOnly = true;
+    } else if (line.startsWith("+++ ") || line.startsWith("Binary files ") || line === "GIT binary patch") {
+      hasContent = true;
+    }
+  }
+  flush();
+  return hunkless;
+}
+var EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+function buildChangedRefHint(cwd, ref) {
+  const countResult = runGit(["rev-list", "--count", "HEAD"], { cwd });
+  if (countResult.exitCode !== 0) {
+    return null;
+  }
+  const commitCount = Number.parseInt(countResult.stdout.trim(), 10);
+  if (!Number.isFinite(commitCount) || commitCount < 1) {
+    return null;
+  }
+  const refResolves = runGit(["rev-parse", "--verify", "--quiet", ref], { cwd });
+  if (refResolves.exitCode === 0) {
+    return null;
+  }
+  let suggestedRef = null;
+  for (let n = commitCount - 1; n >= 1; n--) {
+    const candidate = `HEAD~${n}`;
+    const candidateResolves = runGit(["rev-parse", "--verify", "--quiet", candidate], { cwd });
+    if (candidateResolves.exitCode === 0) {
+      suggestedRef = candidate;
+      break;
+    }
+  }
+  if (suggestedRef === null) {
+    suggestedRef = EMPTY_TREE_HASH;
+  }
+  const commitWord = commitCount === 1 ? "1 commit" : `${commitCount} commits`;
+  return `Hint: this repo has only ${commitWord}; '${ref}' does not exist. Try: token-goat changed --since ${suggestedRef}`;
+}
+function refIsSafe(ref) {
+  return !ref.startsWith("-");
+}
+function emitUnsafeRef(ref) {
+  emitErr(`Refusing a git ref that starts with '-': ${ref}`);
+}
+function literalPathspec(file) {
+  return `:(literal)${file}`;
+}
+function withRenameSources(cwd, ref, files) {
+  const wanted = new Set(files);
+  const paths = [...files];
+  try {
+    const result = runGit(["diff", ref, "--name-status", "-M"], { cwd });
+    if (result.exitCode !== 0) return paths;
+    const unquote = (f) => f.startsWith('"') && f.endsWith('"') && f.length > 1 ? unquoteGitPath(f.slice(1, -1)) : f;
+    for (const row of result.stdout.split(/\r?\n/)) {
+      const [status, from, to] = row.split("	");
+      if (status?.startsWith("R") !== true || from === void 0 || to === void 0) continue;
+      if (wanted.has(unquote(to))) paths.push(unquote(from));
+    }
+  } catch {
+  }
+  return paths;
+}
+function unifiedDiffOf(cwd, ref, files, extraArgs = []) {
+  const run = (paths2) => runGit(["diff", ref, "-M", "--unified=0", ...extraArgs, "--", ...paths2.map(literalPathspec)], { cwd });
+  const first = run(files);
+  if (first.exitCode !== 0 || !first.stdout.includes("--- /dev/null")) return first;
+  const paths = withRenameSources(cwd, ref, files);
+  return paths.length > files.length ? run(paths) : first;
+}
+function changedDiffBaselineBytes(cwd, ref, files) {
+  if (files.length === 0) return 0;
+  try {
+    const result = unifiedDiffOf(cwd, ref, files);
+    if (result.exitCode === 0) return deliveredOutputBytes(Buffer.byteLength(result.stdout, "utf8"));
+  } catch {
+  }
+  return 0;
+}
+function runChanged(opts = {}) {
+  const ref = opts.ref ?? "HEAD~5";
+  if (!refIsSafe(ref)) {
+    emitUnsafeRef(ref);
+    return 1;
+  }
+  const projectDenial = opts.symbolMode === true ? resolveProjectConfinement(opts.projectRoot).denial : null;
+  if (projectDenial !== null) {
+    emitErr(projectDenial);
+    return 1;
+  }
+  const cwd = opts.projectRoot ?? process.cwd();
+  const projectRoot = resolveProjectRoot({ project: cwd });
+  let changedFiles;
+  try {
+    const result = runGit(["diff", ref, "--name-only"], { cwd });
+    if (result.exitCode !== 0) {
+      emitErr(`git diff failed: ${result.stderr}`);
+      const hint = buildChangedRefHint(cwd, ref);
+      if (hint !== null) {
+        emitErr(hint);
+      }
+      return 1;
+    }
+    changedFiles = result.stdout.trim().split(/\r?\n/).filter(Boolean).map((f) => f.startsWith('"') && f.endsWith('"') && f.length > 1 ? unquoteGitPath(f.slice(1, -1)) : f);
+  } catch {
+    emitErr(`Could not run git diff against '${ref}'`);
+    return 1;
+  }
+  const emptyEnvelope = () => {
+    emit(displaySafeJson({ items: [], truncated: false, totalCount: 0 }));
+    return 0;
+  };
+  if (changedFiles.length === 0) {
+    if (opts.json === true) return emptyEnvelope();
+    emit("No files changed.");
+    return 0;
+  }
+  const preGrepFileCount = changedFiles.length;
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  if (matchesGrep !== void 0) changedFiles = changedFiles.filter((f) => matchesGrep(f));
+  if (matchesGrep !== void 0 && changedFiles.length === 0) {
+    if (opts.json === true) return emptyEnvelope();
+    emit(grepFilteredToEmptyNotice(preGrepFileCount, opts.grep ?? "", "changed file", "changed files"));
+    return 0;
+  }
+  const postGrepFileCount = changedFiles.length;
+  let hiddenTestFiles = 0;
+  if (opts.excludeTests === true) {
+    const kept = changedFiles.filter((f) => !isTestFile(f));
+    hiddenTestFiles = changedFiles.length - kept.length;
+    changedFiles = kept;
+  }
+  if (changedFiles.length === 0 && hiddenTestFiles > 0) {
+    if (opts.json === true) return emptyEnvelope();
+    const grepRemoved = preGrepFileCount - postGrepFileCount;
+    if (matchesGrep !== void 0 && grepRemoved > 0) {
+      emit(
+        `No non-test files matched --grep ${opts.grep ?? ""} (${excludeTestsHiddenNote(hiddenTestFiles)}; ${countNoun(grepRemoved, "other changed file")} did not match the filter)`
+      );
+      return 0;
+    }
+    emit(`No non-test files changed (${excludeTestsHiddenNote(hiddenTestFiles)})`);
+    return 0;
+  }
+  if (opts.symbolMode === true) {
+    let hunksByFile = /* @__PURE__ */ new Map();
+    let hunklessFiles = /* @__PURE__ */ new Set();
+    let symbolDiffBaselineBytes = 0;
+    try {
+      const diffResult = unifiedDiffOf(projectRoot, ref, changedFiles, ["--src-prefix=a/", "--dst-prefix=b/"]);
+      if (diffResult.exitCode === 0) {
+        hunksByFile = parseDiffHunks(diffResult.stdout);
+        hunklessFiles = parseHunklessFiles(diffResult.stdout);
+        symbolDiffBaselineBytes = deliveredOutputBytes(Buffer.byteLength(diffResult.stdout, "utf8"));
+      }
+    } catch {
+    }
+    const allSymbols = [];
+    for (const f of changedFiles) {
+      if (hunklessFiles.has(f)) continue;
+      const fileSymbols = querySymbols({ filePath: resolveIndexPath(f, projectRoot), limit: FIND_SCAN_LIMIT });
+      const hunks = hunksByFile.get(f);
+      const scoped = hunks === void 0 || isVirtualIndexedPath(f) ? fileSymbols : fileSymbols.filter((s) => hunks.some((h) => h.start <= s.lineEnd && h.end >= s.lineStart));
+      allSymbols.push(...scoped);
+    }
+    if (allSymbols.length === 0) {
+      if (opts.json === true) return emptyEnvelope();
+      emit("No symbols changed.");
+      return 0;
+    }
+    const symbolFullBytes = symbolDiffBaselineBytes;
+    if (opts.json === true) {
+      const capped = guardJsonRows(allSymbols);
+      const text = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
+      emit(text);
+      recordReadStat("changed_lookup", symbolFullBytes, text, ref);
+      return 0;
+    }
+    const symbolText = allSymbols.map((s) => `${s.name} (${s.kind}) \u2014 ${formatSymbolLocation(toDisplayPath(projectRoot, s.filePath), s.lineStart)}`).join("\n");
+    for (const s of allSymbols) {
+      emit(`${displaySafeText(s.name)} (${displaySafeText(s.kind)}) \u2014 ${formatSymbolLocation(displaySafeText(toDisplayPath(projectRoot, s.filePath)), s.lineStart)}`);
+    }
+    recordReadStat("changed_lookup", symbolFullBytes, symbolText, ref);
+    return 0;
+  }
+  const fullBytes = changedDiffBaselineBytes(projectRoot, ref, changedFiles);
+  if (opts.json === true) {
+    const capped = guardJsonRows(changedFiles);
+    const text = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
+    emit(text);
+    recordReadStat("changed_lookup", fullBytes, text, ref);
+    return 0;
+  }
+  for (const f of changedFiles) {
+    emit(f);
+  }
+  recordReadStat("changed_lookup", fullBytes, changedFiles.join("\n"), ref);
+  return 0;
+}
+function splitDiffHunks(diffText) {
+  const lines = diffText.split(/\r?\n/);
+  let preambleEnd = lines.length;
+  for (let i2 = 0; i2 < lines.length; i2++) {
+    if (HUNK_HEADER_RE.test(lines[i2])) {
+      preambleEnd = i2;
+      break;
+    }
+  }
+  const preamble = lines.slice(0, preambleEnd).join("\n");
+  const hunks = [];
+  let i = preambleEnd;
+  while (i < lines.length) {
+    const line = lines[i];
+    const m = HUNK_HEADER_RE.exec(line);
+    if (m === null) {
+      i++;
+      continue;
+    }
+    const range = hunkHeaderRange(m);
+    const bodyLines = [line];
+    let j = i + 1;
+    while (j < lines.length && !HUNK_HEADER_RE.test(lines[j])) {
+      bodyLines.push(lines[j]);
+      j++;
+    }
+    if (j >= lines.length && bodyLines[bodyLines.length - 1] === "") bodyLines.pop();
+    hunks.push({ text: bodyLines.join("\n"), start: range.start, end: range.end });
+    i = j;
+  }
+  return { preamble, hunks };
+}
+function runDiff(opts) {
+  if (opts.ref !== void 0 && !refIsSafe(opts.ref)) {
+    emitUnsafeRef(opts.ref);
+    return 1;
+  }
+  const match = resolveSymbolSpecOrEmitError("diff", opts.spec, opts.projectRoot);
+  if (match === null) return 1;
+  const cwd = opts.projectRoot ?? process.cwd();
+  const diffArgs = opts.ref !== void 0 ? ["diff", opts.ref, "--unified=0", "--", match.filePath] : ["diff", "--unified=0", "--", match.filePath];
+  let diffResult;
+  try {
+    diffResult = runGit(diffArgs, { cwd });
+  } catch {
+    emitErr(`Could not run git diff for '${match.filePath}'`);
+    return 1;
+  }
+  if (diffResult.exitCode !== 0) {
+    emitErr(`git diff failed: ${diffResult.stderr}`);
+    return 1;
+  }
+  if (diffResult.stdout.trim() === "") {
+    emit(`No changes to '${displaySafeText(match.name)}' in '${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}'.`);
+    return 0;
+  }
+  const { hunks } = splitDiffHunks(diffResult.stdout);
+  const diffFileScoped = isVirtualIndexedPath(match.filePath);
+  const overlapping = diffFileScoped ? hunks : hunks.filter((h) => h.start <= match.lineEnd && h.end >= match.lineStart);
+  if (overlapping.length === 0) {
+    emit(`No changes to '${displaySafeText(match.name)}' (lines ${match.lineStart}-${match.lineEnd}) in '${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}'.`);
+    return 0;
+  }
+  if (opts.json === true) {
+    const capped = guardJsonRows(overlapping.map((h) => ({ start: h.start, end: h.end, text: h.text })));
+    emit(
+      displaySafeJson(
+        {
+          symbol: match.name,
+          file: match.filePath,
+          lineStart: match.lineStart,
+          lineEnd: match.lineEnd,
+          hunks: capped.items,
+          truncated: capped.truncated,
+          totalCount: capped.totalCount
+        }
+      )
+    );
+    return 0;
+  }
+  const header = `# ${displaySafeText(match.name)} (${displaySafeText(match.kind)}) \u2014 ${formatSymbolLocation(displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)), match.lineStart, match.lineEnd)}`;
+  const diffNote = diffFileScoped ? [virtualIndexedScopeNote(displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)), "these hunks cover the whole file rather than this symbol alone")] : [];
+  emit(guardText([header, ...diffNote, ...overlapping.map((h) => h.text)].join("\n"), "diff"));
+  return 0;
+}
+var DEFAULT_LOG_MAX_COUNT = 20;
+function parseLogDashLOutput(stdout) {
+  const lines = stdout.split(/\r?\n/);
+  const commitHeaderRe = /^commit ([0-9a-f]{40})/;
+  const entries = [];
+  let i = 0;
+  while (i < lines.length) {
+    const headerMatch = commitHeaderRe.exec(lines[i]);
+    if (headerMatch === null) {
+      i++;
+      continue;
+    }
+    const hash = headerMatch[1];
+    let author = "";
+    let date = "";
+    let j = i + 1;
+    while (j < lines.length && !commitHeaderRe.test(lines[j])) {
+      const line = lines[j];
+      if (line.startsWith("diff --git")) break;
+      if (author === "" && line.startsWith("Author:")) author = line.slice("Author:".length).trim();
+      else if (date === "" && line.startsWith("Date:")) date = line.slice("Date:".length).trim();
+      j++;
+    }
+    const messageLines = [];
+    for (let k2 = i + 1; k2 < j; k2++) {
+      const line = lines[k2];
+      if (line.startsWith("Author:") || line.startsWith("Date:")) continue;
+      messageLines.push(line.startsWith("    ") ? line.slice(4) : line);
+    }
+    const message = trimBlankLines(messageLines).join("\n");
+    let k = j;
+    while (k < lines.length && !commitHeaderRe.test(lines[k])) k++;
+    const diff = lines.slice(j, k).join("\n");
+    entries.push({ hash, author, date, message, diff });
+    i = k;
+  }
+  return entries;
+}
+function runLog(opts) {
+  if (opts.ref !== void 0 && !refIsSafe(opts.ref)) {
+    emitUnsafeRef(opts.ref);
+    return 1;
+  }
+  const match = resolveSymbolSpecOrEmitError("log", opts.spec, opts.projectRoot);
+  if (match === null) return 1;
+  const cwd = opts.projectRoot ?? process.cwd();
+  const maxCount = opts.maxCount ?? DEFAULT_LOG_MAX_COUNT;
+  const fileScoped = isVirtualIndexedPath(match.filePath);
+  const logArgs = fileScoped ? ["log", `--max-count=${maxCount}`, ...opts.ref !== void 0 ? [opts.ref] : [], "--", match.filePath] : [
+    "log",
+    `-L${match.lineStart},${match.lineEnd}:${match.filePath}`,
+    `--max-count=${maxCount}`,
+    ...opts.ref !== void 0 ? [opts.ref] : []
+  ];
+  let logResult;
+  try {
+    logResult = runGit(logArgs, { cwd });
+  } catch {
+    emitErr(`Could not run git log for '${match.filePath}'`);
+    return 1;
+  }
+  if (logResult.exitCode !== 0) {
+    emitErr(`git log failed: ${displaySafeText(logResult.stderr)}`);
+    return 1;
+  }
+  if (logResult.stdout.trim() === "") {
+    emit(`No history for '${displaySafeText(match.name)}' (lines ${match.lineStart}-${match.lineEnd}) in '${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}'.`);
+    return 0;
+  }
+  if (opts.json === true) {
+    const capped = guardJsonRows(parseLogDashLOutput(logResult.stdout));
+    emit(
+      displaySafeJson(
+        {
+          symbol: match.name,
+          file: match.filePath,
+          lineStart: match.lineStart,
+          lineEnd: match.lineEnd,
+          commits: capped.items,
+          truncated: capped.truncated,
+          totalCount: capped.totalCount
+        }
+      )
+    );
+    return 0;
+  }
+  const header = `# ${displaySafeText(match.name)} (${displaySafeText(match.kind)}) \u2014 ${formatSymbolLocation(displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)), match.lineStart, match.lineEnd)}`;
+  const logNote = fileScoped ? [virtualIndexedScopeNote(displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath)), "this history covers the whole file rather than this symbol alone")] : [];
+  emit(guardText([header, ...logNote, logResult.stdout].join("\n"), "diff"));
+  return 0;
+}
+
+// src/handle_stat.ts
+init_define_import_meta_env();
+import * as fs4 from "node:fs";
+var OPEN_FOR_STAT = process.platform === "win32" ? fs4.constants.O_RDONLY : fs4.constants.O_RDONLY | fs4.constants.O_NONBLOCK;
+function statThroughHandle(p) {
+  const fd = fs4.openSync(p, OPEN_FOR_STAT);
+  try {
+    return fs4.fstatSync(fd, { bigint: true });
+  } finally {
+    fs4.closeSync(fd);
+  }
+}
+
+// src/content_store.ts
+init_define_import_meta_env();
+import { deflateRawSync } from "node:zlib";
+import * as path4 from "node:path";
+var CONTENT_MAX_INPUT_CHARS = 512 * 1024;
+var CONTENT_MAX_ITEMS = 256;
+var CONTENT_MAX_BYTES = 32 * 1024 * 1024;
+var CONTENT_MAX_ITEM_BYTES = CONTENT_MAX_INPUT_CHARS * 7;
+var CONTENT_SUBDIR = "content";
+var TEXT_BYTES_PER_TOKEN = BYTES_PER_TOKEN.text;
+var BASE64URL_BYTES_PER_TOKEN = BYTES_PER_TOKEN.dense;
+function estimateTextTokens(bytes) {
+  return savedTokensFromBytes(bytes, "text");
+}
+function estimateBase64urlTokens(bytes) {
+  return savedTokensFromBytes(bytes, "dense");
+}
+function assertInput(text) {
+  if (text.length > CONTENT_MAX_INPUT_CHARS) {
+    throw new Error(`text exceeds the ${CONTENT_MAX_INPUT_CHARS}-character safety limit`);
+  }
+}
+function contentId(text) {
+  return `tg_${shortFingerprint(text)}`;
+}
+function normalizeProjectRoot(projectRoot) {
+  const candidate = path4.resolve(projectRoot ?? process.cwd());
+  return findProject(candidate)?.root ?? candidate;
+}
+function handoffId(name, projectRoot) {
+  return `tg_handoff_${shortFingerprint(`${projectRoot}\0${name}`)}`;
+}
+function storeContent(text) {
+  const id = contentId(text);
+  const value = { kind: "content", id, text, createdAt: Date.now() };
+  const ok = storeBlob(CONTENT_SUBDIR, id, value, {
+    maxCount: CONTENT_MAX_ITEMS,
+    maxBytes: CONTENT_MAX_BYTES,
+    maxBytesPerItem: CONTENT_MAX_ITEM_BYTES
+  });
+  if (!ok) throw new Error("unable to persist compressed content within the local cache bounds");
+  return id;
+}
+function readContent(id) {
+  if (!/^tg_[0-9a-f]{16}$/.test(id)) return null;
+  if (isBlobStale(CONTENT_SUBDIR, id)) return null;
+  const value = loadBlob(CONTENT_SUBDIR, id);
+  if (value === null || typeof value !== "object" || value === null) return null;
+  const entry = value;
+  return entry.kind === "content" && entry.id === id && typeof entry.text === "string" ? entry.text : null;
+}
+function compressText(text) {
+  assertInput(text);
+  const safeText = redactSecrets(text).text;
+  const id = storeContent(safeText);
+  const compact = deflateRawSync(Buffer.from(safeText, "utf8"), { level: 9 }).toString("base64url");
+  const originalBytes = Buffer.byteLength(safeText, "utf8");
+  const compactBytes = Buffer.byteLength(compact, "utf8");
+  const bytesSaved = Math.max(0, originalBytes - compactBytes);
+  const tokensSaved = estimateTextTokens(originalBytes) - estimateBase64urlTokens(compactBytes);
+  const inlineWins = tokensSaved > 0;
+  recordStat("content_compress", inlineWins ? bytesSaved : 0, inlineWins ? tokensSaved : 0);
+  return {
+    id,
+    compact,
+    encoding: "deflate-raw-base64url",
+    originalBytes,
+    compactBytes,
+    bytesSaved,
+    tokensSaved,
+    inlineWins,
+    recovery: `token-goat retrieve ${id}`
+  };
+}
+function retrieveText(id) {
+  const text = readContent(id);
+  if (text === null) return null;
+  recordStat("content_retrieve");
+  return text;
+}
+function createHandoff(name, text, projectRoot) {
+  if (!/^[A-Za-z0-9._-]{1,128}$/.test(name)) {
+    throw new Error("handoff name must be 1-128 characters using letters, numbers, dot, underscore, or hyphen");
+  }
+  assertInput(text);
+  const root = normalizeProjectRoot(projectRoot);
+  const safeText = redactSecrets(text).text;
+  const contentIdValue = storeContent(safeText);
+  const id = handoffId(name, root);
+  const value = {
+    kind: "handoff",
+    id,
+    name,
+    projectRoot: root,
+    contentId: contentIdValue,
+    // Keep the handoff independently resolvable if the generic content entry
+    // is later evicted from the shared bounded cache.
+    text: safeText,
+    createdAt: Date.now()
+  };
+  const ok = storeBlob(CONTENT_SUBDIR, id, value, {
+    maxCount: CONTENT_MAX_ITEMS,
+    maxBytes: CONTENT_MAX_BYTES,
+    maxBytesPerItem: CONTENT_MAX_ITEM_BYTES
+  });
+  if (!ok) throw new Error("unable to persist handoff within the local cache bounds");
+  recordStat("handoff_create");
+  return { id, name, contentId: contentIdValue, projectRoot: root, recovery: `token-goat handoff-resolve ${name}` };
+}
+function resolveHandoff(name, opts = {}) {
+  const root = normalizeProjectRoot(opts.projectRoot);
+  const id = handoffId(name, root);
+  if (isBlobStale(CONTENT_SUBDIR, id)) return null;
+  const value = loadBlob(CONTENT_SUBDIR, id);
+  if (value === null || typeof value !== "object" || value === null) return null;
+  const entry = value;
+  if (entry.kind !== "handoff" || entry.projectRoot !== root || typeof entry.contentId !== "string" || typeof entry.text !== "string") return null;
+  const text = entry.text;
+  recordStat("handoff_resolve");
+  if (opts.full === true) return text;
+  return compressText(text);
+}
+
+export {
+  WARM_COMMAND,
+  modelDownloadHeld,
+  foregroundDownloadDeferred,
+  downloadAdvice,
+  runtimeDownloadAdvice,
+  checkSemanticReadiness,
+  offlineEmbedNotice,
+  mergeNearbyHits,
+  runSymbol,
+  runBrief,
+  AMBIGUOUS_HEADING_LIMIT,
+  runSection,
+  runZipList,
+  runZipRead,
+  runSqliteSchema,
+  runSqliteTables,
+  runSqliteQuery,
+  runCoverageReportGaps,
+  runConfigGet,
+  runExports,
+  runImports,
+  extractTranscriptText,
+  runNoteGet,
+  runNoteList,
+  runFind,
+  runLocate,
+  runListSections,
+  runSkeleton,
+  runOutline,
+  runSemanticDistances,
+  runSemantic,
+  runSemanticMulti,
+  runRefs,
+  runConflicts,
+  runChanged,
+  runDiff,
+  runLog,
+  statThroughHandle,
+  CONTENT_MAX_INPUT_CHARS,
+  compressText,
+  retrieveText,
+  createHandoff,
+  resolveHandoff
+};