token-goat 2.6.26 → 2.6.27

package/dist/token-goat.mjs

@@ -3050,7 +3050,7 @@ var require_commander = __commonJS({
 import { createRequire } from "node:module";
 function resolveVersion() {
   if (true) {
-    return "2.6.26";
+    return "2.6.27";
   }
   const require2 = createRequire(import.meta.url);
   const pkg = require2("../package.json");
@@ -4720,6 +4720,12 @@ function grepFilteredToEmptyNotice(preFilterCount, grep, nounSingular, nounPlura
   const verb = preFilterCount === 1 ? "was" : "were";
   return `  (all ${preFilterCount} ${noun} ${verb} filtered out by --grep ${grep} -- widen or drop the filter to see them)`;
 }
+function countNoun(count, singular, plural2 = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : plural2}`;
+}
+function excludeTestsHiddenNote(count) {
+  return `${count} in test ${count === 1 ? "file" : "files"} hidden by --exclude-tests`;
+}
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -20677,6 +20683,33 @@ function dirtyQueuePathFor(dir) {
 function drainHeartbeatPathFor(dir) {
   return path17.join(dir, "queue", "drain-heartbeat");
 }
+function writeDrainHeartbeat(dir, force = false) {
+  const now = Date.now();
+  if (!force && now - (heartbeatWriteTimes.get(dir) ?? 0) < WORKER_HEARTBEAT_REFRESH_MS) return;
+  try {
+    fs12.mkdirSync(path17.dirname(drainHeartbeatPathFor(dir)), { recursive: true });
+    fs12.writeFileSync(drainHeartbeatPathFor(dir), `${process.pid}
+`);
+    heartbeatWriteTimes.set(dir, now);
+  } catch {
+  }
+}
+function hasFreshWorkerHeartbeat(dir, pid) {
+  try {
+    const heartbeatPath = drainHeartbeatPathFor(dir);
+    if (Date.now() - fs12.statSync(heartbeatPath).mtimeMs > WORKER_HEARTBEAT_STALE_MS) return false;
+    return fs12.readFileSync(heartbeatPath, "utf8").trim() === String(pid);
+  } catch {
+    return false;
+  }
+}
+function pidFileIsWithinStartupGrace(dir) {
+  try {
+    return Date.now() - fs12.statSync(workerPidPath(dir)).mtimeMs < WORKER_STARTUP_GRACE_MS;
+  } catch {
+    return false;
+  }
+}
 function parseDirtyQueueLines(raw) {
   const seen = /* @__PURE__ */ new Set();
   const out2 = [];
@@ -20864,6 +20897,7 @@ function processDirtyBatch(paths, index = makeIndexer(globalDbPath()), remove =
   let indexed = 0;
   for (const p of paths) {
     if (!p) continue;
+    writeDrainHeartbeat(dir);
     if (isUnderBlockedRoot(p, blockedRoots)) continue;
     if (!fs12.existsSync(p)) {
       remove(p);
@@ -20991,11 +21025,7 @@ function drainOnce(dir, index, remove) {
     }
   }
   for (const p of deferredRequeues) appendToDirtyQueue(dir, p);
-  try {
-    fs12.mkdirSync(path17.dirname(drainHeartbeatPathFor(dir)), { recursive: true });
-    fs12.writeFileSync(drainHeartbeatPathFor(dir), "");
-  } catch {
-  }
+  writeDrainHeartbeat(dir, true);
   return processed;
 }
 function pidAlive(pid) {
@@ -21018,7 +21048,7 @@ function readPidFile(dir) {
 function isWorkerRunning(dir = dataDir()) {
   const pid = readPidFile(dir);
   if (pid === null) return false;
-  return pidAlive(pid);
+  return pidAlive(pid) && hasFreshWorkerHeartbeat(dir, pid);
 }
 function workerHealthCheckMarkerPath(dir) {
   return path17.join(dir, "worker-healthcheck.marker");
@@ -21054,8 +21084,8 @@ function ensureWorkerAlive(dir = dataDir()) {
 function stopWorker(dir = dataDir()) {
   const pid = readPidFile(dir);
   if (pid === null) return false;
-  const alive = pidAlive(pid);
-  if (alive) {
+  const running = isWorkerRunning(dir);
+  if (running) {
     try {
       process.kill(pid);
     } catch {
@@ -21067,7 +21097,7 @@ function stopWorker(dir = dataDir()) {
     } catch {
     }
   }
-  return alive;
+  return running;
 }
 function claimWorkerPidFile(dir, pid) {
   const pidPath = workerPidPath(dir);
@@ -21079,7 +21109,7 @@ function claimWorkerPidFile(dir, pid) {
     if (e.code !== "EEXIST") throw e;
   }
   const existingPid = readPidFile(dir);
-  if (existingPid !== null && pidAlive(existingPid)) {
+  if (existingPid !== null && pidAlive(existingPid) && (hasFreshWorkerHeartbeat(dir, existingPid) || pidFileIsWithinStartupGrace(dir))) {
     return false;
   }
   try {
@@ -21183,9 +21213,10 @@ function runDetachedWorkerDaemon() {
       }
     }
   });
+  writeDrainHeartbeat(dir, true);
   void runWorkerLoop(dir, safeInterval);
 }
-var DEFAULT_POLL_INTERVAL_MS, SNAPSHOT_CLEANUP_INTERVAL_MS, PRUNE_EVERY_N_DRAINS, drainCycleCounts, lastKnownProjectRoots, unclearedDrainingSnapshots, MAX_TRANSIENT_RETRIES, WORKER_ERROR_LOG_MAX_BYTES, CORRUPT_QUARANTINE_MAX_AGE_MS, INDEX_FAILED, inFlightEmbeddings, activeEmbedSlots, embedSlotWaiters, WORKER_HEALTHCHECK_MIN_INTERVAL_MS, WorkerAlreadyRunningError, KNOWN_ROOTS_SWEEP_INTERVAL_MS;
+var DEFAULT_POLL_INTERVAL_MS, WORKER_HEARTBEAT_STALE_MS, WORKER_HEARTBEAT_REFRESH_MS, WORKER_STARTUP_GRACE_MS, SNAPSHOT_CLEANUP_INTERVAL_MS, PRUNE_EVERY_N_DRAINS, drainCycleCounts, heartbeatWriteTimes, lastKnownProjectRoots, unclearedDrainingSnapshots, MAX_TRANSIENT_RETRIES, WORKER_ERROR_LOG_MAX_BYTES, CORRUPT_QUARANTINE_MAX_AGE_MS, INDEX_FAILED, inFlightEmbeddings, activeEmbedSlots, embedSlotWaiters, WORKER_HEALTHCHECK_MIN_INTERVAL_MS, WorkerAlreadyRunningError, KNOWN_ROOTS_SWEEP_INTERVAL_MS;
 var init_worker = __esm({
   "src/worker.ts"() {
     "use strict";
@@ -21205,9 +21236,13 @@ var init_worker = __esm({
     init_project();
     init_reset();
     DEFAULT_POLL_INTERVAL_MS = 2e3;
+    WORKER_HEARTBEAT_STALE_MS = 6e4;
+    WORKER_HEARTBEAT_REFRESH_MS = 5e3;
+    WORKER_STARTUP_GRACE_MS = 1e4;
     SNAPSHOT_CLEANUP_INTERVAL_MS = 60 * 60 * 1e3;
     PRUNE_EVERY_N_DRAINS = 30;
     drainCycleCounts = /* @__PURE__ */ new Map();
+    heartbeatWriteTimes = /* @__PURE__ */ new Map();
     lastKnownProjectRoots = /* @__PURE__ */ new Map();
     unclearedDrainingSnapshots = /* @__PURE__ */ new Map();
     MAX_TRANSIENT_RETRIES = 5;
@@ -23722,6 +23757,12 @@ function didYouMean(candidates) {
   }
   return lines2.join("\n");
 }
+function unknownSymbolSuggestion(name2, rootDir) {
+  const rawSymbols = querySymbols({ limit: FIND_SCAN_LIMIT, rootDir });
+  const candidates = rankSimilarNames(rawSymbols.map((s) => s.name), name2);
+  return candidates.length > 0 ? `
+${didYouMean(candidates)}` : "";
+}
 function formatBareNameSpecError(command, name2, projectRoot) {
   const rootDir = projectRoot ?? resolveProjectRoot({ project: process.cwd() });
   const matches2 = querySymbols({ name: name2, limit: 50, rootDir });
@@ -23795,6 +23836,17 @@ 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 queryOpts = {};
   if (opts.name !== void 0) queryOpts.name = opts.name;
   if (opts.file !== void 0) {
@@ -23802,11 +23854,36 @@ function runSymbol(opts) {
     healStaleIndex(queryOpts.filePath);
   }
   if (opts.kind !== void 0) queryOpts.kind = opts.kind;
-  if (opts.limit !== void 0) queryOpts.limit = opts.limit;
+  if (matchesGrep !== void 0 || excludeTests) {
+    queryOpts.limit = FIND_SCAN_LIMIT;
+  } else if (opts.limit !== void 0) {
+    queryOpts.limit = opts.limit;
+  }
   if (opts.file === void 0 && opts.projectRoot !== void 0) queryOpts.rootDir = opts.projectRoot;
-  const results = querySymbols(queryOpts);
+  const rawResults = querySymbols(queryOpts);
+  const preFilterCount = rawResults.length;
+  const effectiveLimit = opts.limit ?? 100;
+  const anyClientFilter = matchesGrep !== void 0 || excludeTests;
+  const filtered = anyClientFilter ? rawResults.filter((s) => (matchesGrep === void 0 || matchesGrep(s.name)) && !(excludeTests && isTestFile(s.filePath))) : rawResults;
+  const results = anyClientFilter ? filtered.slice(0, effectiveLimit) : filtered;
+  const hiddenByExcludeTests = excludeTests ? rawResults.filter((s) => (matchesGrep === void 0 || matchesGrep(s.name)) && isTestFile(s.filePath)).length : 0;
+  if (excludeTests && filtered.length === 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: JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2), code: 0 };
+    }
+    return { text: `token-goat: ${notice}`, code: 0 };
+  }
+  if (matchesGrep !== void 0 && filtered.length === 0 && preFilterCount > 0) {
+    if (opts.json === true) {
+      const text2 = JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2);
+      return { text: text2, code: 0 };
+    }
+    return { text: grepFilteredToEmptyNotice(preFilterCount, opts.grep ?? "", "symbol", "symbols"), code: 0 };
+  }
   if (results.length === 0) {
-    let text2 = `No matches for '${opts.name ?? "*"}'`;
+    let text2 = `No matches for '${opts.name ?? opts.grep ?? "*"}'`;
     const emptyIndexRoot = opts.json !== true ? opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() }) : null;
     const indexEmpty = emptyIndexRoot !== null && isIndexEmptyForProject(globalDbPath(), emptyIndexRoot);
     if (opts.name !== void 0 && emptyIndexRoot !== null) {
@@ -23827,11 +23904,19 @@ ${emptyIndexMessage(emptyIndexRoot)}`;
   const symbolDisplayRoot = getDisplayRoot(opts.projectRoot);
   if (opts.json === true) {
     const capped = guardJsonRows(results);
-    const trueTotal = countSymbols(queryOpts);
+    let trueTotal;
+    let truncatedFlag;
+    if (anyClientFilter) {
+      trueTotal = filtered.length;
+      truncatedFlag = capped.truncated || results.length < filtered.length;
+    } else {
+      trueTotal = countSymbols(queryOpts);
+      truncatedFlag = capped.truncated || trueTotal > results.length;
+    }
     const items = capped.items.map((s) => ({ ...s, filePath: toDisplayPath(symbolDisplayRoot, s.filePath) }));
-    const payload = { items, truncated: capped.truncated || trueTotal > results.length, totalCount: trueTotal };
+    const payload = { items, truncated: truncatedFlag, totalCount: trueTotal };
     const text2 = JSON.stringify(payload, null, 2);
-    recordReadStat("symbol_lookup", fullSourceBytes, text2, opts.name ?? opts.file);
+    recordReadStat("symbol_lookup", fullSourceBytes, text2, opts.name ?? opts.file ?? opts.grep);
     return { text: text2, code: 0 };
   }
   const blocks = results.map((sym) => {
@@ -23843,7 +23928,7 @@ ${preview}` : header;
   });
   const warning = opts.file !== void 0 ? staleWarning(resolveIndexPath(opts.file, opts.projectRoot ?? process.cwd())) : "";
   const text = guardText(warning + blocks.join("\n\n"), "symbol");
-  recordReadStat("symbol_lookup", fullSourceBytes, text, opts.name ?? opts.file);
+  recordReadStat("symbol_lookup", fullSourceBytes, text, opts.name ?? opts.file ?? opts.grep);
   return { text, code: 0 };
 }
 function parseReadSpec(spec) {
@@ -23912,7 +23997,7 @@ function runLineRange(range2, opts) {
   const allLines = text.split(/\r?\n/);
   if (allLines.length > 1 && allLines[allLines.length - 1] === "") allLines.pop();
   if (start > allLines.length) {
-    return { text: `Line ${start} is past end of file (${allLines.length} lines): ${file2}`, code: 1 };
+    return { text: `Line ${start} is past end of file (${countNoun(allLines.length, "line")}): ${file2}`, code: 1 };
   }
   const clampedEnd = Math.min(end, allLines.length);
   const slice = allLines.slice(start - 1, clampedEnd);
@@ -23948,13 +24033,13 @@ function formatAmbiguity(symbol3, file2, candidates, explicitRoot, commandName =
   const multiFile = new Set(candidates.map((c) => c.filePath)).size > 1;
   const displayRoot = getDisplayRoot(explicitRoot);
   const lines2 = [
-    `Ambiguous symbol '${symbol3}' in '${file2}': ${candidates.length} definitions match. Retry with one of the qualified commands below to pick one:`
+    `Ambiguous symbol '${symbol3}' in '${file2}': ${countNoun(candidates.length, "definition")} match. Retry with one of the qualified commands below to pick one:`
   ];
   const fileSymCache = /* @__PURE__ */ new Map();
   const getFileSyms = (filePath) => {
     let fileSyms = fileSymCache.get(filePath);
     if (fileSyms === void 0) {
-      fileSyms = querySymbols({ filePath, limit: 1e3 });
+      fileSyms = querySymbols({ filePath, limit: FIND_SCAN_LIMIT });
       fileSymCache.set(filePath, fileSyms);
     }
     return fileSyms;
@@ -24340,17 +24425,17 @@ function runRefs(opts) {
         lines2.push(`${sym}: ${grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references").trim()}`);
         continue;
       }
-      lines2.push(opts.excludeTests === true && suppressed > 0 ? `${sym}: (no non-test references found; ${suppressed} in test files hidden by --exclude-tests)` : `${sym}: (no references found)`);
+      lines2.push(opts.excludeTests === true && suppressed > 0 ? `${sym}: (no non-test references found; ${excludeTestsHiddenNote(suppressed)})` : `${sym}: (no references found)`);
       continue;
     }
     lines2.push(`${sym}:`);
     if (opts.top !== void 0) {
       lines2.push(...renderTopFilesSummary(results, opts.top, suppressed));
     } else if (opts.callers === true) {
-      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${results.length} references (${suppressed} in test files hidden by --exclude-tests)`);
+      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`);
       lines2.push(...renderCallerGroups(results, opts.context ?? 0));
     } else {
-      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${results.length} references (${suppressed} in test files hidden by --exclude-tests)`);
+      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`);
       for (const ref2 of results) lines2.push(...renderRefLines(ref2, opts.context ?? 0));
     }
   }
@@ -24411,17 +24496,17 @@ function runRefsCrossFile(pairs, opts) {
         lines2.push(`${key}: ${grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references").trim()}`);
         continue;
       }
-      lines2.push(opts.excludeTests === true && suppressed > 0 ? `${key}: (no non-test references found; ${suppressed} in test files hidden by --exclude-tests)` : `${key}: (no references found)`);
+      lines2.push(opts.excludeTests === true && suppressed > 0 ? `${key}: (no non-test references found; ${excludeTestsHiddenNote(suppressed)})` : `${key}: (no references found)`);
       continue;
     }
     lines2.push(`${key}:`);
     if (opts.top !== void 0) {
       lines2.push(...renderTopFilesSummary(results, opts.top, suppressed));
     } else if (opts.callers === true) {
-      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${results.length} references (${suppressed} in test files hidden by --exclude-tests)`);
+      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`);
       lines2.push(...renderCallerGroups(results, opts.context ?? 0));
     } else {
-      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${results.length} references (${suppressed} in test files hidden by --exclude-tests)`);
+      if (opts.excludeTests === true && suppressed > 0) lines2.push(`  ${countNoun(results.length, "reference")} (${excludeTestsHiddenNote(suppressed)})`);
       for (const ref2 of results) lines2.push(...renderRefLines(ref2, opts.context ?? 0));
     }
   }
@@ -24462,16 +24547,25 @@ function runRefsSingle(opts) {
   }
   if (results.length === 0) {
     if (matchesGrep !== void 0 && preGrepCount > 0) {
+      if (opts.json === true) {
+        emit2(JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2));
+        return 0;
+      }
       emit2(grepFilteredToEmptyNotice(preGrepCount, opts.grep ?? "", "reference", "references"));
       return 0;
     }
     if (opts.excludeTests === true && suppressed > 0) {
-      emitErr(`No non-test references found for '${symName}' (${suppressed} in test files hidden by --exclude-tests)`);
+      emitErr(`No non-test references found for '${symName}' (${excludeTestsHiddenNote(suppressed)})`);
+      return 1;
+    }
+    const rootDir = resolveProjectRoot({ project: process.cwd() });
+    if (querySymbols({ name: symName, rootDir, limit: 1 }).length === 0) {
+      emitErr(`Symbol not found: ${symName}${unknownSymbolSuggestion(symName, rootDir)}`);
+      if (opts.json !== true && isIndexEmptyForProject(globalDbPath(), rootDir)) emitErr(emptyIndexMessage(rootDir));
       return 1;
     }
     emitErr(`No references found for '${symName}'`);
     if (opts.json !== true) {
-      const rootDir = resolveProjectRoot({ project: process.cwd() });
       if (isIndexEmptyForProject(globalDbPath(), rootDir)) emitErr(emptyIndexMessage(rootDir));
     }
     return 1;
@@ -24491,7 +24585,7 @@ function runRefsSingle(opts) {
     recordReadStat("symbol_read", fullSourceBytes, text2, symName);
     return 0;
   }
-  const lines2 = opts.top !== void 0 ? renderTopFilesSummary(results, opts.top, suppressed) : opts.callers === true ? [...opts.excludeTests === true && suppressed > 0 ? [`${results.length} references (${suppressed} in test files hidden by --exclude-tests)`] : [], ...renderCallerGroups(results, opts.context ?? 0)] : [...opts.excludeTests === true && suppressed > 0 ? [`${results.length} references (${suppressed} in test files hidden by --exclude-tests)`] : [], ...results.flatMap((ref2) => renderRefLines(ref2, opts.context ?? 0, ""))];
+  const lines2 = 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((ref2) => renderRefLines(ref2, opts.context ?? 0, ""))];
   const text = lines2.join("\n");
   emitGuarded(text, "symbol");
   recordReadStat("symbol_read", fullSourceBytes, text, symName);
@@ -24509,8 +24603,8 @@ function groupRefsByFile(refs) {
 function renderTopFilesSummary(refs, topN, suppressed) {
   const grouped = groupRefsByFile(refs);
   const shown = grouped.slice(0, topN);
-  const suppressedNote = suppressed !== void 0 && suppressed > 0 ? ` (${suppressed} in test files hidden by --exclude-tests)` : "";
-  const lines2 = [`${refs.length} references across ${grouped.length} files (showing top ${shown.length})${suppressedNote}`];
+  const suppressedNote = suppressed !== void 0 && suppressed > 0 ? ` (${excludeTestsHiddenNote(suppressed)})` : "";
+  const lines2 = [`${countNoun(refs.length, "reference")} across ${countNoun(grouped.length, "file")} (showing top ${shown.length})${suppressedNote}`];
   for (const { file: file2, count } of shown) lines2.push(`  ${count}  ${refsDisplayPath(file2)}`);
   const omittedFiles = grouped.length - shown.length;
   if (omittedFiles > 0) {
@@ -24659,7 +24753,7 @@ function runSkeleton(opts) {
     return { text: text2, code: 0 };
   }
   const totalLines = filtered.length > 0 ? Math.max(...filtered.map((s) => s.lineEnd)) : 0;
-  const lines2 = [`# Skeleton: ${opts.file}  (${filtered.length} symbols, ${totalLines} lines)`];
+  const lines2 = [`# Skeleton: ${opts.file}  (${countNoun(filtered.length, "symbol")}, ${countNoun(totalLines, "line")})`];
   if (filtered.length === 0 && preFilterCount > 0) lines2.push(filteredToEmptyNotice(preFilterCount, opts.minLines, opts.grep));
   for (const sym of filtered) {
     const lineStr = sym.lineStart.toString().padStart(6);
@@ -24699,7 +24793,7 @@ function runOutline(opts) {
     recordReadStat("outline", fullSourceBytes, text2, opts.file);
     return { text: text2, code: 0 };
   }
-  const lines2 = [`# Outline: ${opts.file}  (${filtered.length} symbols)`];
+  const lines2 = [`# Outline: ${opts.file}  (${countNoun(filtered.length, "symbol")})`];
   if (filtered.length === 0 && preFilterCount > 0) lines2.push(filteredToEmptyNotice(preFilterCount, opts.minLines, opts.grep));
   for (const sym of filtered) {
     const rangeStr = `${sym.lineStart.toString().padStart(4)}-${sym.lineEnd.toString().padEnd(6)}`;
@@ -25406,16 +25500,25 @@ function runFind(opts) {
   const symbols = rawSymbols.filter(
     (s) => s.name.toLowerCase().includes(patternLower)
   );
-  const files = [...new Set(symbols.map((s) => s.filePath))].slice(0, opts.limit ?? 50);
+  let fuzzyNames = [];
+  if (symbols.length === 0) {
+    fuzzyNames = rankSimilarNames(rawSymbols.map((s) => s.name), opts.pattern);
+  }
+  const matched = fuzzyNames.length > 0 ? fuzzyNames.flatMap((n) => rawSymbols.filter((s) => s.name === n)) : symbols;
+  const files = [...new Set(matched.map((s) => s.filePath))].slice(0, opts.limit ?? 50);
   const truncated = rawSymbols.length === FIND_SCAN_LIMIT;
   if (files.length === 0) {
     emitErr(`No indexed files match '${opts.pattern}'`);
     return 1;
   }
   if (opts.json === true) {
-    emit2(JSON.stringify({ files, truncated }, null, 2));
+    const fuzzyPayload = fuzzyNames.length > 0 ? { fuzzy: true, matchedNames: fuzzyNames } : {};
+    emit2(JSON.stringify({ files, truncated, ...fuzzyPayload }, null, 2));
     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) {
     emit2(toDisplayPath(rootDir, f));
   }
@@ -25519,7 +25622,12 @@ function runChanged(opts = {}) {
     emitErr(`Could not run git diff against '${ref2}'`);
     return 1;
   }
+  const emptyEnvelope = () => {
+    emit2(JSON.stringify({ items: [], truncated: false, totalCount: 0 }, null, 2));
+    return 0;
+  };
   if (changedFiles.length === 0) {
+    if (opts.json === true) return emptyEnvelope();
     emit2("No files changed.");
     return 0;
   }
@@ -25527,9 +25635,29 @@ function runChanged(opts = {}) {
   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();
     emit2(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) {
+      emit2(
+        `No non-test files matched --grep ${opts.grep ?? ""} (${excludeTestsHiddenNote(hiddenTestFiles)}; ${countNoun(grepRemoved, "other changed file")} did not match the filter)`
+      );
+      return 0;
+    }
+    emit2(`No non-test files changed (${excludeTestsHiddenNote(hiddenTestFiles)})`);
+    return 0;
+  }
   if (opts.symbolMode === true) {
     let hunksByFile = /* @__PURE__ */ new Map();
     try {
@@ -25541,12 +25669,13 @@ function runChanged(opts = {}) {
     }
     const allSymbols = [];
     for (const f of changedFiles) {
-      const fileSymbols = querySymbols({ filePath: resolveIndexPath(f, projectRoot), limit: 1e3 });
+      const fileSymbols = querySymbols({ filePath: resolveIndexPath(f, projectRoot), limit: FIND_SCAN_LIMIT });
       const hunks = hunksByFile.get(f);
       const scoped = hunks === void 0 ? 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();
       emit2("No symbols changed.");
       return 0;
     }
@@ -26525,7 +26654,17 @@ async function runSemantic(query, opts) {
     void 0,
     rootDir
   );
-  const hits = mergeNearbyHits(rawHits).slice(0, n);
+  const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
+  const mergedHits = mergeNearbyHits(rawHits);
+  const preGrepHitCount = mergedHits.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 ? mergedHits.filter(keepHit) : mergedHits;
+  const suppressedHits = opts.excludeTests === true ? mergedHits.filter((h) => (matchesGrep === void 0 || matchesGrep(toDisplayPath(rootDir, h.filePath))) && isTestFile(h.filePath)).length : 0;
+  const hits = filteredHits.slice(0, n);
   if (hits.length > 0) {
     const enclosing = hits.map((h) => resolveEnclosingSymbol(h.filePath, h.startLine));
     if (opts.json === true) {
@@ -26553,8 +26692,41 @@ ${previewLines(h.text, 3)}`;
     recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text2, query);
     return { text: text2, code: 0 };
   }
-  const results = searchSymbolsFts(query, n, void 0, rootDir);
+  let results;
+  let preGrepFtsCount = 0;
+  let suppressedFts = 0;
+  if (anyFilter) {
+    const overFetchFts = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
+    const rawResults = searchSymbolsFts(query, overFetchFts, void 0, rootDir);
+    preGrepFtsCount = rawResults.length;
+    if (opts.excludeTests === true) {
+      suppressedFts = rawResults.filter((s) => (matchesGrep === void 0 || matchesGrep(toDisplayPath(rootDir, s.filePath))) && isTestFile(s.filePath)).length;
+    }
+    results = rawResults.filter(keepHit).slice(0, n);
+  } else {
+    results = searchSymbolsFts(query, n, void 0, rootDir);
+  }
   if (results.length === 0) {
+    const preGrepTotal = preGrepHitCount + preGrepFtsCount;
+    if (matchesGrep !== void 0 && preGrepTotal > 0) {
+      const notice = grepFilteredToEmptyNotice(preGrepTotal, opts.grep ?? "", "match", "matches");
+      if (opts.json === true) {
+        const payload = { source: "fts", items: [], truncated: false, totalCount: 0, grepFilteredToEmpty: true, hint: notice.trim() };
+        return { text: JSON.stringify(payload, null, 2), code: 0 };
+      }
+      return { text: `token-goat: ${notice.trim()}`, code: 0 };
+    }
+    if (opts.excludeTests === true) {
+      const suppressedTotal = suppressedHits + suppressedFts;
+      if (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: JSON.stringify(payload, null, 2), code: 0 };
+        }
+        return { text: `token-goat: ${notice}`, code: 0 };
+      }
+    }
     const indexEmpty = isIndexEmptyForProject(globalDbPath(), rootDir);
     if (opts.json === true) {
       const payload = indexEmpty ? { source: "fts", items: [], truncated: false, totalCount: 0, indexEmpty: true, hint: emptyIndexMessage(rootDir) } : { source: "fts", items: [], truncated: false, totalCount: 0 };
@@ -26814,7 +26986,7 @@ function fileDefinesName(fp, name2, getSyms) {
   return getSyms(fp).some((s) => s.name === name2);
 }
 function filterRefsForSymbol(refs, name2, filePath, getSyms) {
-  return refs.filter((ref2) => ref2.filePath === filePath || !fileDefinesName(ref2.filePath, name2, getSyms));
+  return refs.filter((ref2) => foldPath(ref2.filePath) === foldPath(filePath) || !fileDefinesName(ref2.filePath, name2, getSyms));
 }
 function resolveCallers(name2, limit, filePath, rootDir, excludeTests) {
   const resolvedRootDir = rootDir ?? resolveProjectRoot({ project: process.cwd() });
@@ -26862,7 +27034,12 @@ function runCallers(opts) {
       return 0;
     }
     if (opts.excludeTests === true && suppressed > 0) {
-      emitErr2(`No non-test references found for '${opts.symbol}' (${suppressed} in test files hidden by --exclude-tests)`);
+      emitErr2(`No non-test references found for '${opts.symbol}' (${excludeTestsHiddenNote(suppressed)})`);
+      return 1;
+    }
+    if (querySymbols({ name: name2, rootDir, limit: 1 }).length === 0) {
+      emitErr2(`Symbol not found: ${opts.symbol}${unknownSymbolSuggestion(name2, rootDir)}`);
+      if (opts.json !== true && isIndexEmptyForProject(globalDbPath(), rootDir)) emitErr2(emptyIndexMessage(rootDir));
       return 1;
     }
     emitErr2(`No references found for '${opts.symbol}'`);
@@ -26882,7 +27059,7 @@ function runCallers(opts) {
     return 0;
   }
   if (opts.excludeTests === true && suppressed > 0) {
-    emit3(`${entries.length} callers found (${suppressed} in test files hidden by --exclude-tests)`);
+    emit3(`${countNoun(entries.length, "caller")} found (${excludeTestsHiddenNote(suppressed)})`);
   }
   for (const e of entries) {
     const displayPath = toDisplayPath(rootDir, e.file);
@@ -26908,17 +27085,22 @@ function runCallChain(opts) {
       return 1;
     }
   } else if (querySymbols({ name: name2, rootDir, limit: 1 }).length === 0) {
-    emitErr2(`Symbol not found: ${opts.symbol}`);
+    emitErr2(`Symbol not found: ${opts.symbol}${unknownSymbolSuggestion(name2, rootDir)}`);
     if (opts.json !== true && isIndexEmptyForProject(globalDbPath(), rootDir)) emitErr2(emptyIndexMessage(rootDir));
     return 1;
   }
   const getSyms = buildFileSymCache();
+  let suppressedCount = 0;
   const callersOf = (n) => {
     const refs = queryRefs({ name: n, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
     if (refs.length === 0) return [];
     const scoped = fileHint !== void 0 && n === name2 ? filterRefsForSymbol(refs, n, fileHint, getSyms) : refs;
     const names = /* @__PURE__ */ new Set();
     for (const ref2 of scoped) {
+      if (opts.excludeTests === true && isTestFile(ref2.filePath)) {
+        suppressedCount += 1;
+        continue;
+      }
       const enc = enclosingSymbol(getSyms(ref2.filePath), ref2.line);
       if (enc !== null) names.add(enc.name);
     }
@@ -26930,6 +27112,10 @@ function runCallChain(opts) {
     return 0;
   }
   if (chains.length === 1 && chains[0]?.length === 1 && chains[0][0] === name2) {
+    if (opts.excludeTests === true && suppressedCount > 0) {
+      emit3(`${name2}  (no non-test callers; ${excludeTestsHiddenNote(suppressedCount)})`);
+      return 0;
+    }
     emit3(`${name2}  (no callers)`);
     return 0;
   }
@@ -26959,6 +27145,7 @@ function runImpact(opts) {
   const getSyms = buildFileSymCache();
   const hops = /* @__PURE__ */ new Map([[rootName, 0]]);
   const queue = [[rootName, 0]];
+  let suppressedCount = 0;
   while (queue.length > 0) {
     const item = queue.shift();
     if (item === void 0) break;
@@ -26967,6 +27154,10 @@ function runImpact(opts) {
     const refs = queryRefs({ name: name2, limit: DEFAULT_REF_QUERY_LIMIT, rootDir });
     const scoped = fileHint !== void 0 && name2 === rootName ? filterRefsForSymbol(refs, name2, fileHint, getSyms) : refs;
     for (const ref2 of scoped) {
+      if (opts.excludeTests === true && isTestFile(ref2.filePath)) {
+        suppressedCount += 1;
+        continue;
+      }
       const newHop = depth + 1;
       const enc = enclosingSymbol(getSyms(ref2.filePath), ref2.line);
       if (enc === null) {
@@ -26986,6 +27177,14 @@ function runImpact(opts) {
   hops.delete(rootName);
   const sorted = [...hops.entries()].sort(compareHopEntries).slice(0, top);
   if (sorted.length === 0) {
+    if (opts.excludeTests === true && suppressedCount > 0) {
+      emitErr2(`No non-test impact found for '${opts.symbol}' (${excludeTestsHiddenNote(suppressedCount)})`);
+      return 1;
+    }
+    if (querySymbols({ name: rootName, rootDir, limit: 1 }).length === 0) {
+      emitErr2(`Symbol not found: ${opts.symbol}${unknownSymbolSuggestion(rootName, rootDir)}`);
+      return 1;
+    }
     emitErr2(`No callers found for '${opts.symbol}'`);
     return 1;
   }
@@ -27082,7 +27281,7 @@ function runDead(opts) {
       return 0;
     }
     if (opts.excludeTests === true && suppressed > 0) {
-      emit3(`No dead symbols found (${suppressed} in test files hidden by --exclude-tests).`);
+      emit3(`No dead symbols found (${excludeTestsHiddenNote(suppressed)}).`);
     } else {
       emit3("No dead symbols found.");
     }
@@ -27090,7 +27289,7 @@ function runDead(opts) {
     return 0;
   }
   if (opts.excludeTests === true && suppressed > 0) {
-    emit3(`${sliced.length} dead symbols (${suppressed} in test files hidden by --exclude-tests)`);
+    emit3(`${countNoun(sliced.length, "dead symbol")} (${excludeTestsHiddenNote(suppressed)})`);
   }
   for (const r of sliced) {
     emit3(`${r.name}	${toDisplayPath(rootDir, r.file)}:${r.line}`);
@@ -31217,6 +31416,8 @@ function writeGuidance(filePath) {
     BEGIN,
     buildGuidanceBody("VS Code\u2019s supported MCP integration and its built-in file-read tools"),
     "",
+    "**Compressed payloads:** a message containing a token-goat payload block (recognizable by a `recovery: token-goat retrieve <id>` line) is compressed text, not an answer. Call the MCP tool `retrieve_text` with that id to recover the original text, then answer the question the message asks using the recovered text. Never present the raw payload to the user as the response; if the `retrieve_text` tool is unavailable (the MCP server is not running, or the chat is not in Agent mode), say so plainly and ask the user to switch to Agent mode or run `token-goat install --vscode`.",
+    "",
     "VS Code support: token-goat install --vscode configures a project-local stdio MCP server in .vscode/mcp.json under the servers root key. VS Code may call these MCP tools when selected; MCP does not intercept VS Code\u2019s built-in file reads.",
     END
   ].join("\n");
@@ -65994,7 +66195,6 @@ function checkSymbolCount(dbPath, rootDir) {
   }
 }
 var DIRTY_QUEUE_BACKLOG_WARN_THRESHOLD = 500;
-var DRAIN_HEARTBEAT_STALE_MS = 6e4;
 function checkDirtyQueueHealth(dataDir2) {
   let pendingCount = 0;
   try {
@@ -66017,7 +66217,7 @@ function checkDirtyQueueHealth(dataDir2) {
     heartbeatAgeMs = Date.now() - fs40.statSync(drainHeartbeatPathFor(dataDir2)).mtimeMs;
   } catch {
   }
-  if (heartbeatAgeMs !== null && heartbeatAgeMs > DRAIN_HEARTBEAT_STALE_MS) {
+  if (heartbeatAgeMs !== null && heartbeatAgeMs > WORKER_HEARTBEAT_STALE_MS) {
     return {
       name: "Dirty queue",
       status: "warn",
@@ -82829,7 +83029,12 @@ function requirePositiveInt(flag, raw) {
 }
 async function cmdSemantic(query, opts) {
   const limit = opts.limit !== void 0 ? requireNonNegativeInt("--limit", opts.limit) : 20;
-  const { text, code } = await runSemantic(query, { limit, ...opts.json === true ? { json: true } : {} });
+  const { text, code } = await runSemantic(query, {
+    limit,
+    ...opts.json === true ? { json: true } : {},
+    ...opts.grep !== void 0 ? { grep: opts.grep } : {},
+    ...opts.excludeTests === true ? { excludeTests: true } : {}
+  });
   (opts.json === true || code === 0 ? out : err)(text);
   process.exitCode = code;
 }
@@ -84764,7 +84969,7 @@ function buildProgram() {
       process.exitCode = 1;
     }
   };
-  program2.command("symbol <name>").description("search for a symbol by name").option("-l, --limit <n>", "max results").option("-f, --file <path>", "restrict to one file").option("-k, --kind <kind>", "restrict to one kind (function, class, ...)").option("-p, --project [path]", "scope search to one project root instead of the global index (defaults to cwd)").option("-j, --json", "output as JSON").action((name2, opts) => {
+  program2.command("symbol [name]").description("search for a symbol by name, or project-wide by --grep name pattern").option("-l, --limit <n>", "max results").option("-f, --file <path>", "restrict to one file").option("-k, --kind <kind>", "restrict to one kind (function, class, ...)").option("-p, --project [path]", "scope search to one project root instead of the global index (defaults to cwd)").option("-j, --json", "output as JSON").option("--grep <pattern>", "only show symbols whose name matches this regex (literal substring if it is not valid regex); cannot be combined with <name>").option("--exclude-tests", "hide symbols defined in a test file (opt-in; default output is unchanged)").action((name2, opts) => {
     let projectRoot;
     if (opts.project === true) {
       projectRoot = resolveProjectRoot({ project: process.cwd() });
@@ -84773,12 +84978,14 @@ function buildProgram() {
     }
     return runExitText(
       () => runSymbol({
-        name: name2,
+        ...name2 !== void 0 ? { name: name2 } : {},
         limit: opts.limit !== void 0 ? requireNonNegativeInt("--limit", opts.limit) : 20,
         ...opts.file !== void 0 ? { file: opts.file } : {},
         ...opts.kind !== void 0 ? { kind: opts.kind } : {},
         ...projectRoot !== void 0 ? { projectRoot } : {},
-        ...opts.json === true ? { json: true } : {}
+        ...opts.json === true ? { json: true } : {},
+        ...opts.grep !== void 0 ? { grep: opts.grep } : {},
+        ...opts.excludeTests === true ? { excludeTests: true } : {}
       })
     );
   });
@@ -84811,7 +85018,7 @@ function buildProgram() {
   ).option("-j, --json", "output as JSON").option("--list", "list all section headings in the file instead of reading one").action(
     (spec, opts) => opts.list === true ? runExit(() => runListSections({ file: spec, ...opts.json === true ? { json: true } : {} })) : runExitText(() => runSection({ spec, ...opts.json === true ? { json: true } : {} }))
   );
-  program2.command("semantic <query>").description("semantic search (falls back to full-text search)").option("-l, --limit <n>", "max results").option("-j, --json", "output as JSON").action(guard(cmdSemantic));
+  program2.command("semantic <query>").description("semantic search (falls back to full-text search)").option("-l, --limit <n>", "max results").option("-j, --json", "output as JSON").option("--grep <pattern>", "filter to hits whose file path matches this regex (literal substring if it is not valid regex); matched against the path as rendered").option("--exclude-tests", "hide hits whose file is a test file (opt-in; default output is unchanged)").action(guard(cmdSemantic));
   program2.command("skeleton <file> [more...]").description('list all symbols in a file without bodies (also accepts a comma-separated file list "a,b,c" for one headed block per file)').option("-j, --json", "output as JSON").option("--min-lines <n>", "only show symbols at least N lines long").option("--grep <pattern>", "only show symbols whose name matches this regex (literal substring if it is not valid regex)").option("--force-refresh", "reparse file from disk before querying (ignore stale index)").option("--stats", "add per-symbol reference count and doc-coverage flag").action(
     (file2, more, opts) => runExitText(
       () => noteExtraFileArgs(
@@ -84947,21 +85154,23 @@ function buildProgram() {
       })
     )
   );
-  program2.command("call-chain <symbol>").description("transitive callers up toward entry points (BFS, cycle-safe; accepts file::symbol to disambiguate which same-named definition is meant)").option("-d, --depth <n>", "max BFS depth (default 8)").option("-j, --json", "output as JSON").action(
+  program2.command("call-chain <symbol>").description("transitive callers up toward entry points (BFS, cycle-safe; accepts file::symbol to disambiguate which same-named definition is meant)").option("-d, --depth <n>", "max BFS depth (default 8)").option("-j, --json", "output as JSON").option("--exclude-tests", "hide callers whose call site lives in a test file (opt-in; default output is unchanged)").action(
     (symbol3, opts) => runExit(
       () => runCallChain({
         symbol: symbol3,
         ...opts.depth !== void 0 ? { depth: requireInt("--depth", opts.depth) } : {},
-        ...opts.json === true ? { json: true } : {}
+        ...opts.json === true ? { json: true } : {},
+        ...opts.excludeTests === true ? { excludeTests: true } : {}
       })
     )
   );
-  program2.command("impact <symbol>").description("transitive set of callers impacted by a change (with hop depth; accepts file::symbol to disambiguate which same-named definition is meant)").option("--top <n>", "limit output to top N results").option("-j, --json", "output as JSON").action(
+  program2.command("impact <symbol>").description("transitive set of callers impacted by a change (with hop depth; accepts file::symbol to disambiguate which same-named definition is meant)").option("--top <n>", "limit output to top N results").option("-j, --json", "output as JSON").option("--exclude-tests", "hide callers whose call site lives in a test file (opt-in; default output is unchanged)").action(
     (symbol3, opts) => runExit(
       () => runImpact({
         symbol: symbol3,
         ...opts.top !== void 0 ? { top: requireNonNegativeInt("--top", opts.top) } : {},
-        ...opts.json === true ? { json: true } : {}
+        ...opts.json === true ? { json: true } : {},
+        ...opts.excludeTests === true ? { excludeTests: true } : {}
       })
     )
   );
@@ -85118,13 +85327,14 @@ function buildProgram() {
   }))());
   program2.command("fetch-image <url>").description("fetch an image URL and shrink it (saves to --out path or a temp file)").option("--out <path>", "output file path").option("-j, --json", "output as JSON").action((url2, opts) => guard(() => cmdFetchImage({ url: url2, ...opts.out !== void 0 ? { out: opts.out } : {}, ...opts.json === true ? { json: true } : {} }))());
   program2.command("history").description("show recent session history: bash commands and web fetches (current-session or recent cache)").option("--limit <n>", "max entries to show (default: 30)").option("-j, --json", "output as JSON").action((opts) => guard(() => cmdHistory(opts))());
-  program2.command("changed [ref]").description("list files or symbols changed since a git ref").option("--since <ref>", "git ref to compare against (default: HEAD~5)").option("--symbol", "list symbols instead of files").option("-j, --json", "output as JSON").option("--grep <pattern>", "filter to changed files whose path matches this regex (falls back to a literal substring match when the pattern does not compile); applies to file paths even in --symbol mode").action(
+  program2.command("changed [ref]").description("list files or symbols changed since a git ref").option("--since <ref>", "git ref to compare against (default: HEAD~5)").option("--symbol", "list symbols instead of files").option("-j, --json", "output as JSON").option("--grep <pattern>", "filter to changed files whose path matches this regex (falls back to a literal substring match when the pattern does not compile); applies to file paths even in --symbol mode").option("--exclude-tests", "hide changed files that live in a test file (opt-in; default output is unchanged); applies to file paths even in --symbol mode").action(
     (ref2, opts) => runExit(
       () => runChanged({
         ref: opts.since ?? ref2 ?? "HEAD~5",
         ...opts.symbol === true ? { symbolMode: true } : {},
         ...opts.json === true ? { json: true } : {},
-        ...opts.grep !== void 0 ? { grep: opts.grep } : {}
+        ...opts.grep !== void 0 ? { grep: opts.grep } : {},
+        ...opts.excludeTests === true ? { excludeTests: true } : {}
       })
     )
   );