token-goat 2.8.3 → 2.8.4

package/dist/{token-goat-chunk-C5IL6MJH.mjs → token-goat-chunk-LZOAPGWR.mjs}

@@ -25,7 +25,7 @@ import {
   runSkeleton,
   runSymbol,
   withPinnedReads
-} from "./token-goat-chunk-TX4JFJTD.mjs";
+} from "./token-goat-chunk-RE7S7H26.mjs";
 import {
   buildProjectMap,
   embeddingsDepsAvailable,
@@ -34,7 +34,7 @@ import {
   getProjectIndexCounts,
   isWorkerRunning,
   mapLookupBytesSaved
-} from "./token-goat-chunk-PWVXXPCC.mjs";
+} from "./token-goat-chunk-4OTIB7SB.mjs";
 import {
   VERSION,
   dataDir,
@@ -44,8 +44,9 @@ import {
   loadConfig,
   normalizePath,
   recordStat,
-  resolveProjectRoot
-} from "./token-goat-chunk-6ODZ6PZK.mjs";
+  resolveProjectRoot,
+  savedTokensFromBytes
+} from "./token-goat-chunk-E76UNTVK.mjs";
 import "./token-goat-chunk-AO2QD2AG.mjs";
 import "./token-goat-chunk-AEX54RUZ.mjs";
 
@@ -533,7 +534,7 @@ async function createMcpServer() {
       const map = buildProjectMap(resolveToolRoot(projectRoot), { compact: compact === true });
       const text = formatProjectMap(map, map.compact);
       const bytesSaved = mapLookupBytesSaved(map, text);
-      recordStat("map_lookup", bytesSaved, Math.round(bytesSaved / 4));
+      recordStat("map_lookup", bytesSaved, savedTokensFromBytes(bytesSaved));
       return toCallToolResult({ text, code: 0 });
     }
   );

package/dist/{token-goat-chunk-VAGPOZHO.mjs → token-goat-chunk-NZFTWBGV.mjs}

@@ -10,11 +10,11 @@ import {
   selectFilter,
   shlexSplit,
   wrappedShell
-} from "./token-goat-chunk-EFF2XCLB.mjs";
+} from "./token-goat-chunk-CZALRRGN.mjs";
 import {
   loadConfig,
   recordStat
-} from "./token-goat-chunk-6ODZ6PZK.mjs";
+} from "./token-goat-chunk-E76UNTVK.mjs";
 import "./token-goat-chunk-AO2QD2AG.mjs";
 import "./token-goat-chunk-AEX54RUZ.mjs";
 

package/dist/{token-goat-chunk-TX4JFJTD.mjs → token-goat-chunk-RE7S7H26.mjs}

@@ -39,6 +39,7 @@ import {
   locatePdfPages,
   mergeNearbyHits,
   ocrImage,
+  ocrIntegrityFailed,
   parseWhereSpecs,
   pathEqClause,
   probeImageMeta,
@@ -55,6 +56,7 @@ import {
   shrinkImage,
   storeBlob,
   stripLeadingAttributes,
+  stripTomlComment,
   tomlBracketDelta,
   trimToBudget,
   unzipBounded,
@@ -62,7 +64,7 @@ import {
   walkProject,
   yamlLineClosesQuote,
   yamlOpenQuoteAfter
-} from "./token-goat-chunk-PWVXXPCC.mjs";
+} from "./token-goat-chunk-4OTIB7SB.mjs";
 import {
   Database,
   PER_FILE_COUNTERFACTUAL_CEILING,
@@ -82,6 +84,7 @@ import {
   excludeTestsHiddenNote,
   extractErrorMessage,
   fileIsAbsent,
+  filtersFilteredToEmptyNotice,
   findHtmlHeadingMatches,
   findProject,
   fingerprintContent,
@@ -107,6 +110,7 @@ import {
   resolveIndexPath,
   resolveProjectRoot,
   runGit,
+  savedTokensFromBytes,
   shortFingerprint,
   stripAnsi,
   stripBom,
@@ -114,7 +118,7 @@ import {
   unsupportedLanguageName,
   windowsCmdQuoteArg,
   withExtension
-} from "./token-goat-chunk-6ODZ6PZK.mjs";
+} from "./token-goat-chunk-E76UNTVK.mjs";
 import {
   registerReset
 } from "./token-goat-chunk-AO2QD2AG.mjs";
@@ -198,18 +202,19 @@ function findTableHeaders(lines, isToml) {
       const restStart = closeIdx + openDelim.length;
       const m2 = TABLE_HEADER_RE.exec(line.slice(restStart));
       if (m2 !== null && m2[1] !== void 0) headers.push({ heading: m2[1].trim(), level: 1, index: i });
-      openDelim = lineOpenDelimiterAfter(line, restStart);
+      openDelim = lineOpenDelimiterAfter(stripTomlComment(line.slice(restStart)), 0);
       continue;
     }
     if (isToml && arrayDepth > 0) {
-      arrayDepth = Math.max(0, arrayDepth + tomlBracketDelta(line));
+      arrayDepth = Math.max(0, arrayDepth + tomlBracketDelta(stripTomlComment(line)));
       continue;
     }
     const m = TABLE_HEADER_RE.exec(line);
     if (m !== null && m[1] !== void 0) headers.push({ heading: m[1].trim(), level: 1, index: i });
     if (isToml) {
-      openDelim = lineOpenDelimiterAfter(line, 0);
-      if (openDelim === null) arrayDepth = Math.max(0, tomlBracketDelta(line));
+      const code = stripTomlComment(line);
+      openDelim = lineOpenDelimiterAfter(code, 0);
+      if (openDelim === null) arrayDepth = Math.max(0, tomlBracketDelta(code));
     }
   }
   return headers;
@@ -255,10 +260,11 @@ function findKeyValueHeaders(lines, language) {
       if (closed) openQuote = null;
       continue;
     }
-    const m = (isEnv ? ENV_KEYVALUE_HEADER_RE : KEYVALUE_HEADER_RE).exec(line);
+    const scanned = isEnv ? line.replace(/^[ \t]+/, "") : line;
+    const m = (isEnv ? ENV_KEYVALUE_HEADER_RE : KEYVALUE_HEADER_RE).exec(scanned);
     if (m === null || m[1] === void 0) continue;
     headers.push({ heading: m[1], level: 1, index: i });
-    openQuote = isEnv ? _detectOpenQuote(line.slice(m[0].length)) : yamlOpenQuoteAfter(line, m[0].length);
+    openQuote = isEnv ? _detectOpenQuote(scanned.slice(m[0].length)) : yamlOpenQuoteAfter(line, m[0].length);
   }
   return headers;
 }
@@ -5376,7 +5382,7 @@ function sumFileSizes(filePaths) {
 function recordReadStat(kind, fullSourceBytes, emittedText, detail) {
   const emittedBytes = Buffer.byteLength(emittedText, "utf8");
   const bytesSaved = Math.max(1, fullSourceBytes - emittedBytes);
-  recordStat(kind, bytesSaved, Math.round(bytesSaved / 4), void 0, detail);
+  recordStat(kind, bytesSaved, savedTokensFromBytes(bytesSaved), void 0, detail);
 }
 function findSpecSeparator(spec) {
   return spec.lastIndexOf("::");
@@ -5659,10 +5665,21 @@ function runSymbol(opts) {
     if (opts.name !== void 0 && emptyIndexRoot !== null) {
       const rootDir = emptyIndexRoot;
       const rawSymbols = querySymbols({ limit: FIND_SCAN_LIMIT, rootDir });
-      const candidates = rankSimilarNames(rawSymbols.map((s) => s.name), opts.name);
-      text2 += candidates.length > 0 ? `
+      const exactMatches = rawSymbols.filter((s) => s.name === opts.name);
+      if (exactMatches.length > 0) {
+        const shown = exactMatches.slice(0, DIDYOUMEAN_LIMIT);
+        const where = shown.map((s) => `${s.kind} at ${toDisplayPath(rootDir, s.filePath)}:${s.lineStart}`).join("; ");
+        const more = exactMatches.length > shown.length ? ` (+${exactMatches.length - shown.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 candidates = rankSimilarNames(rawSymbols.map((s) => s.name), opts.name);
+        text2 += candidates.length > 0 ? `
 ${didYouMean(candidates)}` : indexEmpty ? "" : `
 Try: token-goat semantic "${opts.name}"`;
+      }
       const structuredFiles = [...new Set(rawSymbols.map((s) => s.filePath))].sort();
       const hit = findStructuredKeyPath(opts.name, structuredFiles);
       if (hit !== null) {
@@ -5936,9 +5953,11 @@ function resolveSymbolSpec(spec, forceRefresh, projectRoot) {
   let candidates = querySymbols({ name: lookupName, filePath: resolved, limit: 10 });
   if (candidates.length === 0) {
     const foldedFile = foldPath(file);
+    const baseName = file.slice(Math.max(file.lastIndexOf("/"), file.lastIndexOf("\\")) + 1);
     candidates = querySymbols({
       name: lookupName,
       limit: 50,
+      ...baseName !== "" ? { fileBaseName: baseName } : {},
       ...projectRoot !== void 0 ? { rootDir: projectRoot } : {}
     }).filter((s) => {
       const foldedFilePath = foldPath(s.filePath);
@@ -6072,6 +6091,12 @@ ${sub.text}`);
 function resolveAgainstProjectRoot(file, projectRoot) {
   return projectRoot !== void 0 && !path5.isAbsolute(file) ? path5.resolve(projectRoot, file) : file;
 }
+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 runSection(opts) {
   const crossFilePairs = parseCrossFileMultiSpec(opts.spec);
   if (crossFilePairs !== null) return runSectionCrossFile(crossFilePairs, opts);
@@ -6082,7 +6107,7 @@ function runSection(opts) {
   const specFilePath = opts.spec.slice(0, colonIdx);
   const filePath = resolveAgainstProjectRoot(specFilePath, opts.projectRoot);
   const heading = opts.spec.slice(colonIdx + 2);
-  if (heading.includes(",")) {
+  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);
   }
@@ -6516,14 +6541,10 @@ function formatStatsSuffix(refCounts, sym) {
   return refCounts !== void 0 ? `  [${countNoun(refCounts.get(sym.name) ?? 0, "ref")}, ${hasRealDocstring(sym.docstring) ? "documented" : "undocumented"}]` : "";
 }
 function filteredToEmptyNotice(preFilterCount, minLines, grep) {
-  const plural = preFilterCount === 1 ? "symbol" : "symbols";
   const parts = [];
   if (minLines !== void 0) parts.push(`--min-lines ${minLines}`);
   if (grep !== void 0) parts.push(`--grep ${grep}`);
-  const cause = parts.length === 0 ? "the active filter" : parts.join(" + ");
-  const knob = parts.length > 1 ? "filters" : "filter";
-  const verb = preFilterCount === 1 ? "was" : "were";
-  return `  (all ${preFilterCount} indexed ${plural} ${verb} filtered out by ${cause}; the file is indexed -- widen or drop the ${knob} to see them)`;
+  return filtersFilteredToEmptyNotice(preFilterCount, parts, "indexed symbol", "indexed symbols", "the file is indexed");
 }
 function prepareSymbolListing(file, opts) {
   const resolved = resolveIndexPath(file, opts.projectRoot ?? process.cwd());
@@ -6632,6 +6653,12 @@ function runSkeleton(opts) {
   recordReadStat("stub_view", fullSourceBytes, text, opts.file);
   return { text, code: 0 };
 }
+var DOC_SUMMARY_MAX_CHARS = 140;
+function clipDocSummary(firstLine) {
+  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 runOutline(opts) {
   const multiFiles = parseMultiFileSpec(opts.file);
   if (multiFiles !== null) return runPerFileListing(multiFiles, (file) => runOutline({ ...opts, file, includeFilePath: true }), opts.json === true);
@@ -6669,7 +6696,7 @@ function runOutline(opts) {
     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) ? `  # ${sym.docstring.split("\n")[0] ?? ""}` : "";
+    const docFirst = hasRealDocstring(sym.docstring) ? `  # ${clipDocSummary(sym.docstring.split("\n")[0] ?? "")}` : "";
     const statsStr = formatStatsSuffix(refCounts, sym);
     lines.push(`  ${rangeStr}  ${kindStr}  ${sym.name}  (${bodyLen}\u2113)${docFirst}${statsStr}`);
   }
@@ -6709,11 +6736,11 @@ function runCsvQuery(opts) {
       const rowsJson = result.rows.map((r) => Object.fromEntries(result.header.map((h, i) => [h, r[i]])));
       const headTruncated = result.rows.length < result.totalRows;
       const capped = guardJsonRows(rowsJson);
-      const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount: result.totalRows });
+      const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated || headTruncated, totalCount: result.totalRows, ...result.totalRows === 0 && result.preFilterRows > 0 ? { filteredFromRows: result.preFilterRows } : {} });
       emit(jsonText);
       recordReadStat("csv_query", fullSourceBytes, jsonText, opts.file);
     } else {
-      const tableText = formatCsvTable(result);
+      const tableText = formatCsvTable(result, (opts.where ?? []).map((w) => `--where ${w}`));
       emit(tableText);
       recordReadStat("csv_query", fullSourceBytes, tableText, opts.file);
     }
@@ -6856,6 +6883,7 @@ function resolveYamlMergeKeys(node) {
 }
 function parseYamlDocument(text) {
   const docs = loadAll(text).map(resolveYamlMergeKeys);
+  if (docs.length === 0) return null;
   return docs.length === 1 ? docs[0] : docs;
 }
 function runYamlOutline(opts) {
@@ -7439,6 +7467,9 @@ async function runImageText(file) {
   const data = fs5.readFileSync(file);
   const ocr = await ocrImage(data);
   if (ocr === null) {
+    if (ocrIntegrityFailed()) {
+      throw new Error(`${file} was not OCRed: the cached language model failed its checksum and was discarded, so the next run re-downloads it`);
+    }
     if (isOcrEngineAvailable()) {
       throw new Error(`${file} could not be processed by OCR (unreadable image, timeout, or offline model fetch)`);
     }
@@ -7489,15 +7520,14 @@ ${emptyIndexMessage(rootDir2)}`, code: 1 };
   const match = resolution.entry;
   const rootDir = resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() });
   const excludeTests = opts.excludeTests === true;
-  const unboundedQuery = excludeTests || opts.grep !== void 0;
-  const allCallers = resolveCallers(match.name, void 0, match.filePath, rootDir, unboundedQuery);
+  const allCallers = resolveCallers(match.name, void 0, match.filePath, rootDir, true);
   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 = unboundedQuery ? callers.length : queryRefCounts([match.name], globalDbPath(), rootDir).get(match.name) ?? callers.length;
+  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);
@@ -9146,10 +9176,14 @@ function bfsCallChains(start, callersOf, maxDepth) {
     const tip = chain[chain.length - 1];
     if (tip === void 0) continue;
     const callers = callersOf(tip);
-    if (callers.length === 0 || chain.length > maxDepth) {
+    if (callers.length === 0) {
       complete.push(chain);
       continue;
     }
+    if (chain.length > maxDepth) {
+      complete.push([...chain, "(depth-limit)"]);
+      continue;
+    }
     let expanded = false;
     for (const caller of callers) {
       if (chain.includes(caller)) {
@@ -9235,8 +9269,11 @@ function runCallers(opts) {
     emitErr2(`Symbol '${name}' not found in '${file}'`);
     return 1;
   }
-  const unbounded = opts.excludeTests === true || opts.grep !== void 0;
-  const resolved = resolveCallers(name, opts.limit, fileHint, rootDir, unbounded);
+  const unbounded = opts.excludeTests === true || opts.grep !== void 0 || fileHint !== void 0;
+  const requestedLimit = opts.limit ?? DEFAULT_REF_QUERY_LIMIT;
+  const probed = resolveCallers(name, unbounded ? opts.limit : requestedLimit + 1, fileHint, rootDir, unbounded);
+  const sqlTruncated = !unbounded && probed.length > requestedLimit;
+  const resolved = sqlTruncated ? probed.slice(0, requestedLimit) : probed;
   const suppressed = opts.excludeTests === true ? resolved.filter((e) => isTestFile(e.file)).length : 0;
   let filtered = opts.excludeTests === true ? resolved.filter((e) => !isTestFile(e.file)) : resolved;
   const preGrepCount = filtered.length;
@@ -9277,7 +9314,7 @@ function runCallers(opts) {
       return { ...e, file: displayPath, filePath: displayPath };
     });
     const capped = guardJsonRows(rows);
-    const limitTruncated = entries.length < filtered.length;
+    const limitTruncated = entries.length < filtered.length || sqlTruncated;
     const hiddenByGrep = preGrepCount - filtered.length;
     emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated || limitTruncated, totalCount: filtered.length, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...opts.excludeTests === true && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }, null, 2));
     return 0;
@@ -9316,7 +9353,7 @@ function runCallChain(opts) {
   const getSyms = buildFileSymCache();
   let suppressedCount = 0;
   const callersOf = (n) => {
-    const refs = queryRefs({ name: n, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
+    const refs = queryRefs({ name: n, limit: UNBOUNDED_REF_LIMIT, rootDir });
     if (refs.length === 0) return [];
     const scoped = fileHint !== void 0 && n === name ? filterRefsForSymbol(refs, n, fileHint, getSyms) : refs;
     const names = /* @__PURE__ */ new Set();
@@ -9379,12 +9416,16 @@ function runImpact(opts) {
   const hops = /* @__PURE__ */ new Map([[rootName, 0]]);
   const queue = [[rootName, 0]];
   let suppressedCount = 0;
+  let depthCapped = 0;
   while (queue.length > 0) {
     const item = queue.shift();
     if (item === void 0) break;
     const [name, depth] = item;
-    if (depth >= DEPTH_CAP) continue;
-    const refs = queryRefs({ name, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
+    if (depth >= DEPTH_CAP) {
+      depthCapped += 1;
+      continue;
+    }
+    const refs = queryRefs({ name, limit: UNBOUNDED_REF_LIMIT, rootDir });
     const scoped = fileHint !== void 0 && name === rootName ? filterRefsForSymbol(refs, name, fileHint, getSyms) : refs;
     for (const ref of scoped) {
       if (opts.excludeTests === true && isTestFile(ref.filePath)) {
@@ -9412,6 +9453,12 @@ function runImpact(opts) {
   const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
   const grepped = matchesGrep !== void 0 ? allSorted.filter(([symbol]) => matchesGrep(symbol)) : allSorted;
   const sorted = grepped.slice(0, top);
+  if (depthCapped > 0) {
+    emitErr2(`Impact truncated at the ${DEPTH_CAP}-hop depth limit: ${depthCapped} symbol${depthCapped === 1 ? "" : "s"} at that depth ${depthCapped === 1 ? "was" : "were"} not expanded, so callers reachable only beyond ${DEPTH_CAP} hops are missing.`);
+  }
+  if (grepped.length > sorted.length) {
+    emitErr2(`Showing top ${sorted.length} of ${grepped.length} impacted symbols (raise --top to see the rest).`);
+  }
   if (matchesGrep !== void 0 && sorted.length === 0 && allSorted.length > 0) {
     if (opts.json === true) {
       emitErr2(grepFilteredToEmptyNotice(allSorted.length, opts.grep, "impacted symbol", "impacted symbols"));
@@ -9541,14 +9588,17 @@ function runDead(opts) {
     }
     return 1;
   }
-  const syms = kinds.flatMap((k) => querySymbols({ kind: k, limit: 5e3, rootDir }));
+  const syms = kinds.flatMap((k) => querySymbols({ kind: k, limit: UNBOUNDED_REF_LIMIT, rootDir }));
   const getSyms = buildFileSymCache();
   const results = [];
   let suppressed = 0;
   for (const sym of syms) {
     if (opts.includePrivate !== true && sym.name.startsWith("_")) continue;
     const refs = queryRefs({ name: sym.name, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
-    const scoped = filterRefsForSymbol(refs, sym.name, sym.filePath, getSyms);
+    let scoped = filterRefsForSymbol(refs, sym.name, sym.filePath, getSyms);
+    if (scoped.length === 0 && refs.length >= DEFAULT_REF_QUERY_LIMIT) {
+      scoped = filterRefsForSymbol(queryRefs({ name: sym.name, limit: UNBOUNDED_REF_LIMIT, rootDir }), sym.name, sym.filePath, getSyms);
+    }
     if (!isDeadSymbol(sym.name, scoped.length)) continue;
     if (sym.kind === "method") {
       const ownScope = enclosingNamedScope(getSyms(sym.filePath), sym.lineStart);
@@ -9883,7 +9933,7 @@ function runScope(opts) {
   }
   const filePath = resolveIndexPath(file);
   const syms = querySymbols({ filePath, limit: ALL_SYMBOLS_IN_FILE_LIMIT });
-  const enclosing = syms.filter((s) => s.lineStart <= line && line <= s.lineEnd).sort((a, b) => b.lineStart - a.lineStart);
+  const enclosing = syms.filter((s) => s.lineStart <= line && line <= s.lineEnd).sort((a, b) => b.lineStart - a.lineStart || a.lineEnd - b.lineEnd || a.name.localeCompare(b.name, "en"));
   if (syms.length === 0) {
     if (!fs6.existsSync(filePath)) {
       emitErr2(`Could not read: ${file}`);
@@ -9967,17 +10017,18 @@ function canonicalCycleKey(cyclePath) {
   }
   return [...nodes.slice(minIdx), ...nodes.slice(0, minIdx)].join(" ");
 }
-function findCycles(graph) {
+function findCyclesCapped(graph) {
   const cycles = [];
   const seen = /* @__PURE__ */ new Set();
   const sccs = tarjanSCCs(graph);
+  const probeLimit = MAX_CYCLES + 1;
   for (const component of sccs) {
     let dfs2 = function(start, node, pathSoFar) {
-      if (cycles.length >= MAX_CYCLES) return;
+      if (cycles.length >= probeLimit) return;
       stack.add(node);
       for (const nb of graph.get(node) ?? []) {
         if (!sccSet.has(nb)) continue;
-        if (cycles.length >= MAX_CYCLES) break;
+        if (cycles.length >= probeLimit) break;
         if (nb === start) {
           const cyclePath = [...pathSoFar, node, start];
           const key = canonicalCycleKey(cyclePath);
@@ -9992,6 +10043,7 @@ function findCycles(graph) {
       stack.delete(node);
     };
     var dfs = dfs2;
+    if (cycles.length >= probeLimit) break;
     if (component.length === 1) {
       const [only] = component;
       if (only !== void 0 && (graph.get(only) ?? []).includes(only)) cycles.push([only, only]);
@@ -10000,11 +10052,12 @@ function findCycles(graph) {
     const sccSet = new Set(component);
     const stack = /* @__PURE__ */ new Set();
     for (const start of component) {
-      if (cycles.length >= MAX_CYCLES) break;
+      if (cycles.length >= probeLimit) break;
       dfs2(start, start, []);
     }
   }
-  return cycles;
+  if (cycles.length > MAX_CYCLES) return { cycles: cycles.slice(0, MAX_CYCLES), truncated: true };
+  return { cycles, truncated: false };
 }
 function runSimilar(opts) {
   if (opts.top !== void 0 && opts.top <= 0) {
@@ -10108,8 +10161,8 @@ function runCoverageGaps(opts) {
   }
   const top = opts.top ?? 50;
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const allFns = querySymbols({ kind: "function", limit: 2e3, rootDir });
-  const allMethods = querySymbols({ kind: "method", limit: 2e3, rootDir });
+  const allFns = querySymbols({ kind: "function", limit: UNBOUNDED_REF_LIMIT, rootDir });
+  const allMethods = querySymbols({ kind: "method", limit: UNBOUNDED_REF_LIMIT, rootDir });
   const candidates = [...allFns, ...allMethods];
   const gaps = [];
   for (const sym of candidates) {
@@ -10120,6 +10173,9 @@ function runCoverageGaps(opts) {
     if (!hasTestRef) gaps.push({ name: sym.name, kind: sym.kind, file: sym.filePath, line: sym.lineStart });
   }
   const sliced = gaps.slice(0, top);
+  if (gaps.length > sliced.length) {
+    emitErr2(`Showing top ${sliced.length} of ${gaps.length} coverage gaps (raise --top to see the rest).`);
+  }
   if (opts.json === true) {
     emit2(JSON.stringify(sliced, null, 2));
     return 0;
@@ -10188,16 +10244,16 @@ function runArch(opts) {
   }
   const hubs = [...importedBy.entries()].sort((a, b) => b[1].size - a[1].size).slice(0, top).map(([f, importers]) => ({ file: f, importedBy: importers.size }));
   const entryPoints = files.filter((f) => !importedBy.has(f) && (graph.get(f) ?? []).length > 0).slice(0, top).map((f) => ({ file: f }));
-  const cycles = findCycles(graph);
+  const { cycles, truncated: cyclesTruncated } = findCyclesCapped(graph);
   if (opts.json === true) {
-    emit2(JSON.stringify({ hubs, entryPoints, cycles }, null, 2));
+    emit2(JSON.stringify({ hubs, entryPoints, cycles, ...cyclesTruncated ? { cyclesTruncated: true } : {} }, null, 2));
     return 0;
   }
   emit2(`hubs (top ${top} most-imported):`);
   for (const h of hubs) emit2(`  ${h.importedBy} importers	${toDisplayPath(getDisplayRoot(opts.cwd), h.file)}`);
   emit2(`entry points (imported by nobody, top ${top}):`);
   for (const e of entryPoints) emit2(`  ${toDisplayPath(getDisplayRoot(opts.cwd), e.file)}`);
-  emit2(`cycles (${cycles.length} found):`);
+  emit2(cyclesTruncated ? `cycles (first ${cycles.length}, truncated at the ${MAX_CYCLES}-cycle enumeration limit: more cycles exist):` : `cycles (${cycles.length} found):`);
   for (const c of cycles) emit2(`  ${c.map((f) => toDisplayPath(getDisplayRoot(opts.cwd), f)).join(" -> ")}`);
   return 0;
 }
@@ -10249,17 +10305,21 @@ function runAsk(opts) {
   const BACKEND_ENV = "TOKEN_GOAT_ASK_BACKEND";
   const backendLabel = process.env[BACKEND_ENV] ?? "";
   const entries = hits.map((h) => ({ file: h.filePath, symbol: h.name, kind: h.kind, line: h.lineStart, readCmd: `token-goat read "${h.filePath}::${h.name}@${h.lineStart}"` }));
-  const degrade = () => {
+  const degrade = (reason, extraNote) => {
     if (opts.json === true) {
-      emit2(JSON.stringify({ degraded: true, note: `Set ${BACKEND_ENV}=claude|codex for LLM synthesis`, context: entries }, null, 2));
+      emit2(JSON.stringify({ degraded: true, note: reason, ...extraNote !== void 0 ? { hint: extraNote } : {}, context: entries }, null, 2));
       return 0;
     }
-    emit2(`[degraded mode - set ${BACKEND_ENV}=claude|codex for LLM synthesis]`);
+    emit2(`[degraded mode - ${reason}]`);
+    if (extraNote !== void 0) emit2(extraNote);
     for (const e of entries) emit2(`token-goat read "${toDisplayPath(rootDir, e.file)}::${e.symbol}@${e.line}"`);
     return 0;
   };
-  if (!backendLabel) return degrade();
-  if (hits.length === 0) return degrade();
+  if (!backendLabel) return degrade(`set ${BACKEND_ENV}=claude|codex for LLM synthesis`);
+  if (hits.length === 0) {
+    if (isIndexEmptyForProject(globalDbPath(), rootDir)) return degrade(`${BACKEND_ENV}=${backendLabel} is set, but nothing is indexed for this project yet, so there is no context to answer from`, emptyIndexMessage(rootDir));
+    return degrade(`${BACKEND_ENV}=${backendLabel} is set, but no indexed symbol matched this question, so there is no context to answer from -- try different wording or token-goat semantic`);
+  }
   const isWin = process.platform === "win32";
   let backendPath = null;
   try {
@@ -10268,7 +10328,7 @@ function runAsk(opts) {
     if (found) backendPath = found;
   } catch {
   }
-  if (!backendPath) return degrade();
+  if (!backendPath) return degrade(`${BACKEND_ENV}=${backendLabel} is set, but '${backendLabel}' was not found on PATH`);
   const context = hits.map((h, i) => `[${i + 1}] ${h.filePath}
 ${h.body ?? ""}`).join("\n\n");
   const prompt = `Answer the QUESTION using only the CODE SNIPPETS below.
@@ -10319,7 +10379,7 @@ ANSWER:`;
       }
     }
   }
-  return degrade();
+  return degrade(`${BACKEND_ENV}=${backendLabel} ran but returned no answer`);
 }
 
 // src/content_store.ts