token-goat 2.9.30 → 2.9.31

package/dist/{token-goat-chunk-CZ3LUXYZ.mjs → token-goat-chunk-VIHGGGEI.mjs}

@@ -7,28 +7,35 @@ import {
   getSqliteSchema,
   getSqliteTables,
   runReadOnlySqliteQuery
-} from "./token-goat-chunk-ZCDTCVIS.mjs";
+} from "./token-goat-chunk-YKB6AQG3.mjs";
 import {
+  WHOLE_FILE_NOTE_SYMBOL,
+  getNote,
+  isNoteStale,
+  listNotes
+} from "./token-goat-chunk-COPNXRJM.mjs";
+import {
+  CORE_SYMBOL_KINDS,
   DELETED_TAG,
   DIDYOUMEAN_LIMIT,
   FIND_SCAN_LIMIT,
   FirstRows,
   REF_BLIND_DEF_PROBE_LIMIT,
   UNBOUNDED_QUERY_LIMIT,
-  WHOLE_FILE_NOTE_SYMBOL,
   buildContextWindow,
   compareBinary,
   confinedProjectRoot,
   confinementRefusal,
+  couldNotReadError,
   didYouMean,
-  emit,
-  emitErr,
+  docCommentLines,
   emitGuarded,
   extractExportNames,
   extractImports,
   fileConfinementRefusal,
   fileExists,
   fileIsGone,
+  fileNotFoundError,
   filterSimilarHeadings,
   findSpecSeparator,
   findStructuredKeyPath,
@@ -37,7 +44,6 @@ import {
   formatAmbiguity,
   formatBareNameSpecError,
   formatStatsSuffix,
-  getNote,
   guardJsonRows,
   guardText,
   hasRealDocstring,
@@ -46,17 +52,17 @@ import {
   importsExtensionFor,
   indexFileSyncPinned,
   indexFreshness,
-  isNoteStale,
   isRefIndexedFile,
   isValidUtf8,
   largestFileSize,
-  listNotes,
   nearNamesSkippedNote,
   nearSymbolNames,
   noSymbolsMessage,
   parseCrossFileMultiSpec,
   parseMultiFileSpec,
   parseReadSpec,
+  parseYamlDocument,
+  parseYamlDocumentAsWritten,
   previewLines,
   projectStructuredFiles,
   rankSimilarNames,
@@ -90,10 +96,27 @@ import {
   typedRefsForDef,
   unknownSymbolSuggestion,
   warnIfFilesStale
-} from "./token-goat-chunk-PU7V3FD6.mjs";
+} from "./token-goat-chunk-4SC7UJYV.mjs";
 import {
+  emit,
+  emitErr,
   parseJsonOrJsonc
-} from "./token-goat-chunk-XKI4SEMX.mjs";
+} from "./token-goat-chunk-QQTWJY2O.mjs";
+import {
+  emptyIndexMessage,
+  getEmbeddingCoverage,
+  isIgnoredIndexPath,
+  isIndexEmptyForProject,
+  walkProject
+} from "./token-goat-chunk-ZNMNUPAZ.mjs";
+import {
+  capListField,
+  guardAndFenceFileText
+} from "./token-goat-chunk-M52KPT3C.mjs";
+import {
+  filtersFilteredToEmptyNotice,
+  grepFilteredToEmptyNotice
+} from "./token-goat-chunk-CJLS3CDL.mjs";
 import {
   MODEL_DOWNLOAD_HOST,
   RUNTIME_DOWNLOAD_HOST,
@@ -101,34 +124,42 @@ import {
   isExplicitDownload,
   lastDownloadFailure,
   withExplicitDownload
-} from "./token-goat-chunk-SMVRN2HU.mjs";
+} from "./token-goat-chunk-2UPZGKKY.mjs";
 import {
   commentSyntaxFor
 } from "./token-goat-chunk-5RG5SBL6.mjs";
 import {
   deliveredOutputBytes
-} from "./token-goat-chunk-54K3EUV3.mjs";
+} from "./token-goat-chunk-DOWRSMWO.mjs";
 import {
   NOTEBOOK_CELL_LINES_SUFFIX,
-  emptyIndexMessage,
   formatSymbolLocation,
-  getEmbeddingCoverage,
-  isIgnoredIndexPath,
-  isIndexEmptyForProject,
+  indexedSourceText,
   isVirtualIndexedPath,
-  searchEvidenceSemantically,
-  virtualIndexedScopeNote,
-  walkProject
-} from "./token-goat-chunk-FBNQNSJK.mjs";
+  virtualIndexedScopeNote
+} from "./token-goat-chunk-QH7YVYOY.mjs";
+import {
+  searchEvidenceSemantically
+} from "./token-goat-chunk-NOSS5VWY.mjs";
 import {
   enqueueDirtyPathSafe
-} from "./token-goat-chunk-H2PHHGM5.mjs";
+} from "./token-goat-chunk-CIMQ2BB3.mjs";
 import {
-  ensureWorkerAlive,
-  fetchBypassesProxy,
-  nodeFetchHonoursEnvProxy,
-  proxyConfigured
-} from "./token-goat-chunk-5KDMCMF2.mjs";
+  isBlobStale,
+  loadBlob,
+  storeBlob
+} from "./token-goat-chunk-4ZBFWLXF.mjs";
+import {
+  CliError,
+  formatCommandError,
+  formatFailedResultText,
+  formatGitFailure
+} from "./token-goat-chunk-CBIQ7WTD.mjs";
+import {
+  findContainingSection,
+  listSections,
+  readSection
+} from "./token-goat-chunk-OXFMP75N.mjs";
 import {
   MAX_OVER_FETCH,
   NATIVE_RUNTIME_INSTALL,
@@ -139,15 +170,12 @@ import {
   checkEmbeddingPreflight,
   eachUnfencedLine,
   embeddingBackendLoadError,
-  findContainingSection,
   isAvailable,
-  listSections,
   modelDir,
   modelFilesPresent,
-  readSection,
   searchSemantic,
   wasmBinaryPresent
-} from "./token-goat-chunk-RHXKCZX3.mjs";
+} from "./token-goat-chunk-NISNMD7T.mjs";
 import {
   ATX_CLASS_BREAK_RE,
   matchAtxHeading
@@ -156,48 +184,61 @@ import {
   DEFAULT_QUERY_LIMIT,
   countRefs,
   countSymbols,
+  distinctSymbolKinds,
   queryRefCounts,
   queryRefs,
   querySymbols,
   searchSymbolsFts
-} from "./token-goat-chunk-HYBFA5X3.mjs";
+} from "./token-goat-chunk-IK2DRMFX.mjs";
 import {
-  isBlobStale,
-  loadBlob,
-  storeBlob
-} from "./token-goat-chunk-ARDNEC2U.mjs";
+  fenceFileFieldIfMatched,
+  fenceJsonStrings
+} from "./token-goat-chunk-4NAPX7BA.mjs";
 import {
-  BYTES_PER_TOKEN,
-  getGlobalDb,
+  readGlobalDb,
   recordStat,
   savedTokensFromBytes,
   withTelemetryWriteDb
-} from "./token-goat-chunk-3Z5S4KGM.mjs";
+} from "./token-goat-chunk-U4WHMG6Y.mjs";
 import {
   detectLanguage,
   detectLanguageOfFile,
-  getDb
-} from "./token-goat-chunk-VL3YIFHZ.mjs";
+  getReadDb
+} from "./token-goat-chunk-GVB2MUST.mjs";
+import {
+  forClient
+} from "./token-goat-chunk-KGEFFSHD.mjs";
+import {
+  BYTES_PER_TOKEN
+} from "./token-goat-chunk-XX6O25RN.mjs";
+import {
+  ensureWorkerAlive,
+  fetchBypassesProxy,
+  nodeFetchHonoursEnvProxy,
+  proxyConfigured
+} from "./token-goat-chunk-F6PAUIEK.mjs";
 import {
   redactSecrets
-} from "./token-goat-chunk-4FVIAHSI.mjs";
+} from "./token-goat-chunk-T5P5ACNQ.mjs";
 import {
-  findProject,
-  getDisplayRoot,
   getProjectConfigInfo,
   loadConfig,
   parse,
+  resolveConfigKeyLayer
+} from "./token-goat-chunk-7EZTZOMC.mjs";
+import {
+  findProject,
+  getDisplayRoot,
   projectHash,
-  resolveConfigKeyLayer,
   resolveProjectRoot,
   shortFingerprint
-} from "./token-goat-chunk-7IN2MKDS.mjs";
+} from "./token-goat-chunk-4GBVPH3D.mjs";
 import {
   MAX_ZIP_OUTPUT_BYTES,
   ZipInputTooLargeError,
   ZipOutputTooLargeError,
   unzipBounded
-} from "./token-goat-chunk-XTQAOTSO.mjs";
+} from "./token-goat-chunk-EDBDRVH5.mjs";
 import {
   createLazyModuleLoader
 } from "./token-goat-chunk-AH6QILZM.mjs";
@@ -207,13 +248,17 @@ import {
   escapeRegExp,
   excludeTestsHiddenNote,
   extractErrorMessage,
-  filtersFilteredToEmptyNotice,
-  grepFilteredToEmptyNotice,
   isTestFile,
   requireNonNegativeStrictInt,
   runGit,
   stripBom
-} from "./token-goat-chunk-GOLEOXZP.mjs";
+} from "./token-goat-chunk-HU4TORC5.mjs";
+import {
+  canQuoteArg,
+  echoedValue,
+  fencedCommand,
+  quotedArg
+} from "./token-goat-chunk-GGGG7RWB.mjs";
 import {
   foldPath
 } from "./token-goat-chunk-AM5V6GSX.mjs";
@@ -227,7 +272,7 @@ import {
 import {
   SKELETON_SYMBOL_CAP,
   globalDbPath
-} from "./token-goat-chunk-VES7EL7O.mjs";
+} from "./token-goat-chunk-CO3UYX6G.mjs";
 import {
   init_define_import_meta_env
 } from "./token-goat-chunk-A37V4PBF.mjs";
@@ -301,7 +346,7 @@ function explainModelDownload(result, now = Date.now()) {
   }
   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.`;
+    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 ${countNoun(result.indexedFiles, "indexed file")} 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);
@@ -314,7 +359,7 @@ function offlineEmbedNotice(fileCount, 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.`;
+  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 model can be downloaded, or copy the pinned model files into ${modelDir()}; then run \`token-goat index\` again.`;
 }
 
 // src/read_symbol.ts
@@ -329,7 +374,7 @@ function stableSortImportBindsLast(rows) {
 }
 function runSymbol(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
-    return { text: `--limit must be a positive number, got: ${opts.limit}`, code: 1 };
+    return { text: `--limit must be a positive number, got: ${echoedValue(String(opts.limit))}`, code: 1 };
   }
   if (opts.name !== void 0 && opts.grep !== void 0) {
     return {
@@ -429,7 +474,7 @@ function runSymbol(opts) {
   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)})`;
+    const notice = `no non-test matches for ${echoedValue(label)} (${excludeTestsHiddenNote(hiddenByExcludeTests)})`;
     if (opts.json === true) {
       return { text: displaySafeJson({ items: [], truncated: false, totalCount: 0 }), code: 0 };
     }
@@ -446,7 +491,19 @@ function runSymbol(opts) {
     if (opts.json === true) {
       return { text: displaySafeJson({ items: [], truncated: false, totalCount: 0 }), code: 0 };
     }
-    let text2 = `No matches for '${opts.name ?? opts.grep ?? "*"}'`;
+    let text2 = `No matches for ${echoedValue(opts.name ?? opts.grep ?? "*")}`;
+    if (opts.kind !== void 0 && !CORE_SYMBOL_KINDS.includes(opts.kind)) {
+      const storedKinds = distinctSymbolKinds(opts.projectRoot);
+      if (!storedKinds.includes(opts.kind)) {
+        text2 += `
+no indexed symbol has kind ${echoedValue(opts.kind)}`;
+        const lower = opts.kind.toLowerCase();
+        const recased = [.../* @__PURE__ */ new Set([...storedKinds, ...CORE_SYMBOL_KINDS])].filter((k) => k.toLowerCase() === lower);
+        const closes = recased.length > 0 ? recased : rankSimilarNames(storedKinds, opts.kind);
+        if (closes.length > 0) text2 += `
+${didYouMean(closes)}`;
+      }
+    }
     const emptyIndexRoot = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
     const indexEmpty = isIndexEmptyForProject(globalDbPath(), emptyIndexRoot);
     if (opts.name !== void 0) {
@@ -459,11 +516,11 @@ function runSymbol(opts) {
         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}`;
+${echoedValue(opts.name)} IS indexed (${where}${more}) -- ${widen}`;
       } else {
         const near = nearSymbolNames(opts.name, rootDir);
-        const semanticHint = indexEmpty ? "" : `
-Try: token-goat semantic "${opts.name}"`;
+        const semanticHint = indexEmpty || !canQuoteArg(opts.name) ? "" : `
+Try: token-goat semantic ${quotedArg(opts.name)}`;
         if (near.skipped) text2 += `
 ${nearNamesSkippedNote()}${semanticHint}`;
         else text2 += near.candidates.length > 0 ? `
@@ -474,7 +531,7 @@ ${didYouMean(near.candidates)}` : semanticHint;
       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}'`;
+${echoedValue(opts.name)} is a key in ${display} at ${hit.dotPath} -- JSON/YAML keys below the top level are not symbols; read it with: ${fencedCommand(`token-goat ${hit.command} ${quotedArg(display)} ${quotedArg(hit.dotPath)}`)}`;
       }
     }
     if (indexEmpty) {
@@ -519,13 +576,15 @@ ${emptyIndexMessage(emptyIndexRoot)}`;
     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 doc = docCommentLines(sym);
+    const docLabel = doc.length > 0 ? ` + ${doc.length}-line doc comment` : "";
+    const header = `# ${displaySafeText(sym.name)} (${sym.kind}) \u2014 ${formatSymbolLocation(displaySafeText(toDisplayPath(symbolDisplayRoot, sym.filePath)), sym.lineStart, sym.lineEnd)}${docLabel}${statsStr}${goneTag}${staleTag}`;
     const body = resolveBody(sym);
     const bodyLines = body.split(/\r?\n/);
-    const preview = bodyLines.slice(0, SYMBOL_PREVIEW_LINES).join("\n");
+    const preview = [...doc, ...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}")` : "";
+    const elided = dropped > 0 ? forClient(`
+  ...(${countNoun(dropped, "more line")}; full body: ${fencedCommand("token-goat read " + quotedArg(`${displaySafeText(toDisplayPath(symbolDisplayRoot, sym.filePath))}::${displaySafeText(sym.name)}`))})`) : "";
     return preview.trim() !== "" ? `${header}
 ${preview}${elided}` : header;
   });
@@ -570,11 +629,11 @@ function runBriefCore(opts) {
     if (opts.json !== true) {
       const rootDir2 = resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() });
       if (isIndexEmptyForProject(globalDbPath(), rootDir2)) {
-        return { text: `Symbol not found: ${opts.spec}
+        return { text: `Symbol not found: ${echoedValue(opts.spec)}
 ${emptyIndexMessage(rootDir2)}`, code: 1 };
       }
     }
-    return { text: `Symbol not found: ${opts.spec}`, code: 1 };
+    return { text: `Symbol not found: ${echoedValue(opts.spec)}`, code: 1 };
   }
   const match = resolution.entry;
   const rootDir = specScopeRoot(opts.spec, resolveProjectRoot({ project: opts.projectRoot ?? process.cwd() })).root;
@@ -627,8 +686,8 @@ ${emptyIndexMessage(rootDir2)}`, code: 1 };
     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 callerDisplayPath = displaySafeText(toDisplayPath(rootDir, c.file));
+    lines.push(`  ${displaySafeText(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, "", "    "));
   }
@@ -686,14 +745,14 @@ ${sub.text}`);
 }
 function runBrief(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
-    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    emitErr(formatCommandError(`--limit must be a positive number, got: ${echoedValue(String(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);
+    else emitErr(formatFailedResultText(text2));
     return code2;
   }
   const { file, symbol } = parseReadSpec(opts.spec);
@@ -702,13 +761,13 @@ function runBrief(opts) {
     if (multiSymbols.length > 1) {
       const { text: text2, code: code2 } = runBriefMulti(file, multiSymbols, opts);
       if (code2 === 0) emit(text2);
-      else emitErr(text2);
+      else emitErr(formatFailedResultText(text2));
       return code2;
     }
   }
   const { text, code } = runBriefCore(opts);
   if (code === 0) emit(text);
-  else emitErr(text);
+  else emitErr(formatFailedResultText(text));
   return code;
 }
 
@@ -785,7 +844,7 @@ function runSection(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 };
+      return { text: fileNotFoundError(filePath).message, code: 1 };
     }
     const ordSpec = /^(.*?)#(\d+)$/.exec(heading);
     const ordBase = ordSpec?.[1]?.trim();
@@ -794,25 +853,25 @@ function runSection(opts) {
       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}`,
+          text: `Heading ${quotedArg(ordBase)} has ${countNoun(total, "occurrence")} in ${quotedArg(specFilePath)}; valid ordinals are #1 to #${total}`,
           code: 1
         };
       }
     }
-    const messages = [`Section '${heading}' not found in '${filePath}'`];
+    const messages = [`Section ${quotedArg(heading)} not found in ${quotedArg(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}`);
+    else if (allHeadings.length === 0) messages.push(`${quotedArg(specFilePath)} has no headings`);
+    else messages.push(`Try: token-goat outline ${quotedArg(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:`
+      `Ambiguous heading ${quotedArg(heading)} in ${quotedArg(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}"`);
+      lines.push(`  - line ${line}  ->  token-goat section ${quotedArg(`${specFilePath}::${heading}#${i + 1}`)}`);
     }
     if (result.occurrences.length > AMBIGUOUS_HEADING_LIMIT) {
       lines.push(`  (${result.occurrences.length - AMBIGUOUS_HEADING_LIMIT} more not shown)`);
@@ -860,7 +919,7 @@ ${filtered.matched} of ${filtered.total} lines matched`;
     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 redirectNote = result.redirectedFrom !== void 0 ? ` (redirected from: ${echoedValue(result.redirectedFrom)})` : "";
   const text = guardText(
     `# ${result.heading} \u2014 ${filePath}:${result.lineStart}-${lineEnd}${redirectNote}${content.length > 0 ? `
 ${content}` : ""}${truncatedNotice}${grepNote}`,
@@ -882,7 +941,7 @@ function runSectionMulti(specFilePath, resolvedFilePath, headings, opts) {
       );
       if (parent !== void 0) {
         anyFound = true;
-        const notice = `(already included in section '${parent.heading}', lines ${sectionResult.lineStart}-${sectionResult.lineEnd})`;
+        const notice = `(already included in section ${quotedArg(parent.heading)}, lines ${sectionResult.lineStart}-${sectionResult.lineEnd})`;
         if (opts.json === true) {
           jsonOut[heading] = {
             heading: sectionResult.heading,
@@ -938,7 +997,7 @@ function runSectionCrossFile(pairs, opts) {
       );
       if (parent !== void 0) {
         anyFound = true;
-        const notice = `(already included in section '${parent.heading}', lines ${sectionResult.lineStart}-${sectionResult.lineEnd})`;
+        const notice = `(already included in section ${quotedArg(parent.heading)}, lines ${sectionResult.lineStart}-${sectionResult.lineEnd})`;
         if (opts.json === true) {
           jsonOut[key] = {
             heading: sectionResult.heading,
@@ -1331,9 +1390,10 @@ function formatCoverageGaps(report) {
 }
 
 // src/read_inspect.ts
+var BINARY_ENTRY_ELIDED = "[binary content elided by token-goat]";
 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}`;
+  return `Failed to read archive (not a valid zip-format file): ${echoedValue(file)}`;
 }
 async function runZipList(opts) {
   let data;
@@ -1341,30 +1401,30 @@ async function runZipList(opts) {
     data = readFileBytes(opts.file);
   } catch (err) {
     if (err instanceof ZipInputTooLargeError) {
-      emitErr(err.message);
+      emitErr(formatCommandError(err.message));
       return 1;
     }
     throw err;
   }
   if (data === null) {
-    emitErr(`Could not read: ${opts.file}`);
+    emitErr(formatCommandError(couldNotReadError(opts.file)));
     return 1;
   }
   let entries;
   try {
     entries = await listZipEntries(data);
   } catch (err) {
-    emitErr(archiveReadFailure(err, opts.file));
+    emitErr(formatCommandError(archiveReadFailure(err, opts.file)));
     return 1;
   }
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = displaySafeJson(entries, 0);
+    const jsonText = displaySafeJson(entries.map((e) => ({ ...e, path: fenceFileFieldIfMatched(e.path) })), 0);
     emit(jsonText);
     recordReadStat("zip_list", fullSourceBytes, jsonText, opts.file);
   } else {
-    const text = formatZipList(entries);
-    emitGuarded(text, "zip-list");
+    const text = guardAndFenceFileText(formatZipList(entries), "zip-list");
+    emit(text);
     recordReadStat("zip_list", fullSourceBytes, text, opts.file);
   }
   return 0;
@@ -1375,13 +1435,13 @@ async function runZipRead(opts) {
     data = readFileBytes(opts.file);
   } catch (err) {
     if (err instanceof ZipInputTooLargeError) {
-      emitErr(err.message);
+      emitErr(formatCommandError(err.message));
       return 1;
     }
     throw err;
   }
   if (data === null) {
-    emitErr(`Could not read: ${opts.file}`);
+    emitErr(formatCommandError(couldNotReadError(opts.file)));
     return 1;
   }
   let entries;
@@ -1390,32 +1450,33 @@ async function runZipRead(opts) {
     entries = await listZipEntries(data);
     content = await extractZipEntry(data, opts.entry);
   } catch (err) {
-    emitErr(archiveReadFailure(err, opts.file));
+    emitErr(formatCommandError(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}'`);
+    emitErr(formatCommandError(`Entry ${echoedValue(opts.entry)} is a directory, not a file, in ${echoedValue(opts.file)}`));
     return 1;
   }
   if (content === void 0) {
-    const messages = [`Entry '${opts.entry}' not found in '${opts.file}'`];
+    const messages = [`Entry ${echoedValue(opts.entry)} not found in ${echoedValue(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"));
+    else if (entries.length > 0) messages.push(`Try: token-goat zip-list ${quotedArg(opts.file)}`);
+    emitErr(formatCommandError(new CliError(messages)));
     return 1;
   }
   const buf = Buffer.from(content);
-  const text = isValidUtf8(buf) ? buf.toString("utf-8") : "[binary content elided by token-goat]";
+  const text = isValidUtf8(buf) ? buf.toString("utf-8") : null;
   const fullSourceBytes = sumFileSizes([opts.file]);
   if (opts.json === true) {
-    const jsonText = displaySafeJson({ path: opts.entry, text }, 0);
+    const jsonText = displaySafeJson({ path: opts.entry, text: text === null ? BINARY_ENTRY_ELIDED : fenceFileFieldIfMatched(text) }, 0);
     emit(jsonText);
     recordReadStat("zip_read", fullSourceBytes, jsonText, opts.entry);
   } else {
-    emitGuarded(text, "zip-read");
-    recordReadStat("zip_read", fullSourceBytes, text, opts.entry);
+    const printed = text === null ? BINARY_ENTRY_ELIDED : guardAndFenceFileText(text, "zip-read");
+    emit(printed);
+    recordReadStat("zip_read", fullSourceBytes, printed, opts.entry);
   }
   return 0;
 }
@@ -1424,17 +1485,17 @@ function runSqliteSchema(opts) {
     const schema = getSqliteSchema(opts.file);
     const fullSourceBytes = sumFileSizes([opts.file]);
     if (opts.json === true) {
-      const jsonText = displaySafeJson(schema, 0);
+      const jsonText = capListField(schema, "tables", (o) => displaySafeJson(fenceJsonStrings(o, fenceFileFieldIfMatched), 0));
       emit(jsonText);
       recordReadStat("sqlite_schema", fullSourceBytes, jsonText, opts.file);
     } else {
-      const text = formatSqliteSchema(schema);
+      const text = guardAndFenceFileText(formatSqliteSchema(schema), "sqlite-schema");
       emit(text);
       recordReadStat("sqlite_schema", fullSourceBytes, text, opts.file);
     }
     return 0;
   } catch (e) {
-    emitErr(extractErrorMessage(e));
+    emitErr(formatCommandError(e));
     return 1;
   }
 }
@@ -1443,17 +1504,21 @@ function runSqliteTables(opts) {
     const tables = getSqliteTables(opts.file);
     const fullSourceBytes = sumFileSizes([opts.file]);
     if (opts.json === true) {
-      const jsonText = displaySafeJson(tables, 0);
+      const jsonText = capListField({ items: tables }, "items", (o) => displaySafeJson(fenceJsonStrings(o.truncated === true ? o : o.items, fenceFileFieldIfMatched), 0));
+      if (jsonText.startsWith("{")) {
+        const cut = JSON.parse(jsonText);
+        emitErr(`token-goat: sqlite-tables --json shows ${cut.items.length} of ${cut.totalCount} tables, the most that fit overflow_guard.max_tokens; list fewer with sqlite-query.`);
+      }
       emit(jsonText);
       recordReadStat("sqlite_tables", fullSourceBytes, jsonText, opts.file);
     } else {
-      const text = formatSqliteTables(tables);
+      const text = guardAndFenceFileText(formatSqliteTables(tables), "sqlite-tables");
       emit(text);
       recordReadStat("sqlite_tables", fullSourceBytes, text, opts.file);
     }
     return 0;
   } catch (e) {
-    emitErr(extractErrorMessage(e));
+    emitErr(formatCommandError(e));
     return 1;
   }
 }
@@ -1462,7 +1527,7 @@ function runSqliteQuery(opts) {
   try {
     head = opts.head !== void 0 ? requireNonNegativeStrictInt("--head", opts.head) : void 0;
   } catch (e) {
-    emitErr(extractErrorMessage(e));
+    emitErr(formatCommandError(e));
     return 1;
   }
   try {
@@ -1471,9 +1536,9 @@ function runSqliteQuery(opts) {
     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 capped = guardJsonRows(rows.map((r) => fenceJsonStrings(r, fenceFileFieldIfMatched)));
       const jsonText = displaySafeJson({
-        columns: result.columns,
+        columns: result.columns.map(fenceFileFieldIfMatched),
         items: capped.items,
         truncated: capped.truncated || headTruncated || result.rowCapped,
         totalCount,
@@ -1490,29 +1555,28 @@ function runSqliteQuery(opts) {
       }, 0);
       recordReadStat("sqlite_query", Buffer.byteLength(baselineJsonText, "utf8"), jsonText, opts.file);
     } else {
-      const text = formatSqliteQueryTable({ ...result, rows }, { headTruncated });
+      const text = guardAndFenceFileText(formatSqliteQueryTable({ ...result, rows }, { headTruncated }), "sqlite-query");
       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));
+    emitErr(formatCommandError(e));
     return 1;
   }
 }
 function runCoverageReportGaps(opts) {
   const text = readFileText(opts.file);
   if (text === null) {
-    emitErr(`Could not read: ${opts.file}`);
+    emitErr(formatCommandError(couldNotReadError(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)}`);
+    emitErr(formatCommandError(new CliError([`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;
@@ -1560,30 +1624,22 @@ function stripPairedQuotes(s) {
   }
   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++;
+function lookupYaml(text, key) {
+  let typed;
+  let written;
+  try {
+    typed = parseYamlDocument(text);
+    written = parseYamlDocumentAsWritten(text);
+  } catch {
+    return void 0;
   }
-  return null;
+  const parts = key.split(".").map((name) => ({ name, joinable: true }));
+  const found = resolveConfigKey(typed, parts);
+  if (found === void 0) return null;
+  if (found === null) return "null";
+  if (typeof found === "object" && !(found instanceof Date)) return displaySafeJson(found, 0);
+  const asWritten = resolveConfigKey(written, parts);
+  return typeof asWritten === "string" ? asWritten : String(found);
 }
 function extractFrontmatter(lines) {
   if (lines[0]?.trim() !== "---") return null;
@@ -1597,14 +1653,18 @@ function extractFrontmatter(lines) {
 function runConfigGet(opts) {
   const text = readFileText(opts.file);
   if (text === null) {
-    emitErr(`Could not read: ${opts.file}`);
+    emitErr(formatCommandError(couldNotReadError(opts.file)));
     return 1;
   }
   const frontmatterLines = extractFrontmatter(text.split(/\r?\n/));
   if (frontmatterLines !== null) {
-    const value = lookupYaml(frontmatterLines, opts.key);
+    const value = lookupYaml(frontmatterLines.join("\n"), opts.key);
+    if (value === void 0) {
+      emitErr(formatCommandError(`Failed to parse YAML frontmatter: ${echoedValue(opts.file)}`));
+      return 1;
+    }
     if (value === null) {
-      emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+      emitErr(formatCommandError(`Key ${echoedValue(opts.key)} not found in ${echoedValue(opts.file)}`));
       return 1;
     }
     emit(value);
@@ -1616,26 +1676,30 @@ function runConfigGet(opts) {
       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}`);
+          emitErr(formatCommandError(`Key ${echoedValue(opts.key)} not found in ${echoedValue(opts.file)}`));
           return 1;
         }
         obj = obj[part];
         if (obj === void 0) {
-          emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+          emitErr(formatCommandError(`Key ${echoedValue(opts.key)} not found in ${echoedValue(opts.file)}`));
           return 1;
         }
       }
       emit(displaySafeJson(obj, 0));
       return 0;
     } catch {
-      emitErr(`Failed to parse JSON: ${opts.file}`);
+      emitErr(formatCommandError(`Failed to parse JSON: ${echoedValue(opts.file)}`));
       return 1;
     }
   }
   if (ext === ".yaml" || ext === ".yml") {
-    const value = lookupYaml(text.split(/\r?\n/), opts.key);
+    const value = lookupYaml(text, opts.key);
+    if (value === void 0) {
+      emitErr(formatCommandError(`Failed to parse YAML: ${echoedValue(opts.file)}`));
+      return 1;
+    }
     if (value === null) {
-      emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+      emitErr(formatCommandError(`Key ${echoedValue(opts.key)} not found in ${echoedValue(opts.file)}`));
       return 1;
     }
     emit(value);
@@ -1645,7 +1709,7 @@ function runConfigGet(opts) {
     const toml = lookupToml(text, opts.key);
     if (toml !== void 0) {
       if (toml === null) {
-        emitErr(`Key '${opts.key}' not found in ${opts.file}`);
+        emitErr(formatCommandError(`Key ${echoedValue(opts.key)} not found in ${echoedValue(opts.file)}`));
         return 1;
       }
       emit(toml);
@@ -1661,14 +1725,14 @@ function runConfigGet(opts) {
     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`);
+        emitErr(formatCommandError(`Key ${echoedValue(opts.key)} in ${echoedValue(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}`);
+  emitErr(formatCommandError(`Key ${echoedValue(opts.key)} not found in ${echoedValue(opts.file)}`));
   return 1;
 }
 function isTomlFragment(v) {
@@ -1698,7 +1762,7 @@ function tomlProbePath(key, value) {
     return null;
   }
 }
-function resolveTomlKey(node, parts) {
+function resolveConfigKey(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;
@@ -1706,7 +1770,7 @@ function resolveTomlKey(node, parts) {
     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));
+    const found = resolveConfigKey(table[head], parts.slice(n));
     if (found !== void 0) return found;
   }
   return void 0;
@@ -1718,7 +1782,7 @@ function lookupToml(text, key) {
   } catch {
     return void 0;
   }
-  const found = resolveTomlKey(doc, splitTomlKeyPath(key));
+  const found = resolveConfigKey(doc, splitTomlKeyPath(key));
   if (found === void 0) return null;
   if (typeof found === "string") return found;
   if (typeof found === "object" && found !== null && !(found instanceof Date)) {
@@ -1766,7 +1830,7 @@ function runExports(opts) {
   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);
+    emitErr(formatCommandError(confined));
     return 1;
   }
   const diskPath = resolveAgainstProjectRoot(opts.file, opts.projectRoot);
@@ -1785,7 +1849,7 @@ function runExports(opts) {
   const ext = path.extname(opts.file).toLowerCase();
   const text = readFileText(diskPath);
   if (text === null && symbols.length === 0) {
-    emitErr(`Could not read: ${opts.file}`);
+    emitErr(formatCommandError(couldNotReadError(opts.file)));
     return 1;
   }
   if (text !== null) {
@@ -1795,7 +1859,7 @@ function runExports(opts) {
     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)}'`);
+    emit(`No exported symbols found in ${echoedValue(opts.file)}`);
     return 0;
   }
   const preFilterCount = names.length;
@@ -1828,7 +1892,7 @@ function runExports(opts) {
   const outLines = filteredNames.map((n) => {
     const loc = locOf(n);
     const locSuffix = loc === null ? "" : ` (${loc.lineStart}-${loc.lineEnd})`;
-    return `${kindOf(n).padEnd(10)} ${n}${locSuffix}`;
+    return `${kindOf(n).padEnd(10)} ${displaySafeText(n)}${locSuffix}`;
   });
   for (const line of outLines) {
     emit(line);
@@ -1842,12 +1906,12 @@ function runImports(opts) {
   const diskPath = resolveAgainstProjectRoot(opts.file, opts.projectRoot);
   const text = readFileText(diskPath);
   if (text === null) {
-    emitErr(`Could not read: ${opts.file}`);
+    emitErr(formatCommandError(couldNotReadError(opts.file)));
     return 1;
   }
   const imports = extractImports(text, importsExtensionFor(opts.file));
   if (imports.length === 0) {
-    emit(`No imports found in '${displaySafeText(opts.file)}'`);
+    emit(`No imports found in ${echoedValue(opts.file)}`);
     return 0;
   }
   const preFilterCount = imports.length;
@@ -1918,8 +1982,8 @@ function runNoteGet(opts) {
   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 where = opts.symbol !== void 0 ? ` for symbol ${echoedValue(opts.symbol)}` : " (whole-file note)";
+    return { text: `No note found for ${echoedValue(opts.file)}${where}`, code: 1 };
   }
   const stale = isNoteStale(note);
   if (opts.json === true) {
@@ -1973,7 +2037,7 @@ function runNoteList(opts = {}) {
 }
 function runFind(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
-    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    emitErr(formatCommandError(`--limit must be a positive number, got: ${echoedValue(String(opts.limit))}`));
     return 1;
   }
   const rootDir = resolveProjectRoot({ project: process.cwd() });
@@ -2001,7 +2065,7 @@ function runFind(opts) {
   const limitDropped = allFiles.length - files.length;
   const truncated = limitDropped > 0;
   if (files.length === 0) {
-    emitErr(`No indexed files match '${opts.pattern}'`);
+    emitErr(formatCommandError(`No indexed files match ${echoedValue(opts.pattern)}`));
     return 1;
   }
   if (opts.json === true) {
@@ -2010,10 +2074,10 @@ function runFind(opts) {
     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(", ")}`);
+    emitErr(`No symbol name contains ${echoedValue(opts.pattern)}; showing files for the nearest indexed ${fuzzyNames.length === 1 ? "name" : "names"}: ${fuzzyNames.map(displaySafeText).join(", ")}`);
   }
   for (const f of files) {
-    emit(toDisplayPath(rootDir, f));
+    emit(displaySafeText(toDisplayPath(rootDir, f)));
   }
   if (limitDropped > 0) {
     emitErr(`Showing ${files.length} of ${allFiles.length} matching files; rerun with --limit ${allFiles.length} to see them all`);
@@ -2022,7 +2086,7 @@ function runFind(opts) {
 }
 function runLocate(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
-    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    emitErr(formatCommandError(`--limit must be a positive number, got: ${echoedValue(String(opts.limit))}`));
     return 1;
   }
   const rootDir = opts.projectRoot ?? resolveProjectRoot({ project: process.cwd() });
@@ -2081,7 +2145,7 @@ function runLocate(opts) {
   }
   const shown = sinkGoneRows(combined, (s) => s.filePath).slice(0, limit);
   if (shown.length === 0) {
-    emitErr(`No landmark or symbol located for '${targetSpec}'`);
+    emitErr(formatCommandError(`No landmark or symbol located for ${echoedValue(targetSpec)}`));
     return 1;
   }
   warnIfFilesStale(shown.map((s) => s.filePath), "locate");
@@ -2104,7 +2168,7 @@ function runLocate(opts) {
     return 0;
   }
   if (fuzzyNames.length > 0) {
-    emitErr(`No exact landmark for '${targetSpec}'; nearest matches: ${fuzzyNames.join(", ")}`);
+    emitErr(`No exact landmark for ${echoedValue(targetSpec)}; nearest matches: ${fuzzyNames.map(displaySafeText).join(", ")}`);
   }
   for (const hit of hits) {
     emit(`${displaySafeText(hit.filePath)}:${hit.span} [${displaySafeText(hit.kind)}] ${displaySafeText(hit.name)}${hit.deleted === true ? `  ${DELETED_TAG}` : ""}`);
@@ -2118,10 +2182,10 @@ function runListSections(opts) {
   const sections = listSections(opts.file);
   if (sections.length === 0) {
     if (!fileExists(opts.file)) {
-      emitErr(`Could not read: ${opts.file}`);
+      emitErr(formatCommandError(couldNotReadError(opts.file)));
       return 1;
     }
-    emitErr(`No sections found in '${opts.file}'`);
+    emitErr(formatCommandError(`No sections found in ${echoedValue(opts.file)}`));
     return 1;
   }
   const preFilterCount = sections.length;
@@ -2156,6 +2220,7 @@ function runListSections(opts) {
 
 // src/read_outline.ts
 init_define_import_meta_env();
+import * as fs2 from "node:fs";
 var DOC_SUMMARY_MAX_CHARS = 140;
 function firstSentenceEnd(line) {
   const MIN_SENTENCE_CHARS = 30;
@@ -2169,12 +2234,24 @@ function firstSentenceEnd(line) {
   }
   return null;
 }
-function clipDocSummary(firstLine) {
+function fileLineCount(resolved, symbolExtent) {
+  try {
+    const text = indexedSourceText(resolved, fs2.readFileSync(resolved, "utf8"));
+    if (text === "") return symbolExtent;
+    const lines = text.split("\n");
+    return Math.max(symbolExtent, text.endsWith("\n") ? lines.length - 1 : lines.length);
+  } catch {
+    return symbolExtent;
+  }
+}
+function clipDocSummary(docstring) {
+  const [firstLine = "", ...rest] = docstring.split("\n");
+  const more = rest.some((l) => l.trim() !== "") ? "\u2026" : "";
   const sentence = firstSentenceEnd(firstLine);
   if (sentence !== null && sentence <= DOC_SUMMARY_MAX_CHARS) {
-    return sentence === firstLine.length ? firstLine : `${firstLine.slice(0, sentence)}\u2026`;
+    return sentence === firstLine.length ? `${firstLine}${more}` : `${firstLine.slice(0, sentence)}\u2026`;
   }
-  if (firstLine.length <= DOC_SUMMARY_MAX_CHARS) return firstLine;
+  if (firstLine.length <= DOC_SUMMARY_MAX_CHARS) return `${firstLine}${more}`;
   const cut = firstLine.lastIndexOf(" ", DOC_SUMMARY_MAX_CHARS);
   return `${firstLine.slice(0, cut > 40 ? cut : DOC_SUMMARY_MAX_CHARS).trimEnd()}\u2026`;
 }
@@ -2222,7 +2299,7 @@ function prepareSymbolListing(file, opts) {
   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 };
+  return { kind: "ok", resolved, displayRoot: getDisplayRoot(opts.projectRoot), filtered, preFilterCount: scanned, refCounts, fullSourceBytes, symbolsTruncated, trueSymbolCount, totalLines: fileLineCount(resolved, totalLines) };
 }
 function runPerFileListing(files, run, json = false) {
   const blocks = [];
@@ -2292,12 +2369,12 @@ function runSkeleton(opts) {
     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")})`];
+  const lines = [`# Skeleton: ${displaySafeText(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}`);
+    lines.push(`  ${lineStr}  ${sym.kind.padEnd(10)}  ${displaySafeText(sym.name)}  ${displaySafeText(firstBodyLine(sym.body))}${statsStr}`);
   }
   const text = guardText(staleWarning(resolved, "skeleton") + lines.join("\n"), "symbol");
   recordReadStat("stub_view", fullSourceBytes, text, opts.file);
@@ -2334,16 +2411,16 @@ function runOutline(opts) {
     recordReadStat("outline", fullSourceBytes, text2, opts.file);
     return { text: text2, code: 0 };
   }
-  const lines = [`# Outline: ${opts.file}  (${symbolCountLabel(filtered.length, symbolsTruncated, trueSymbolCount)})`];
+  const lines = [`# Outline: ${displaySafeText(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 docFirst = hasRealDocstring(sym.docstring) ? `  # ${displaySafeText(clipDocSummary(sym.docstring))}` : "";
     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}`);
+    lines.push(`  ${rangeStr}  ${kindStr}  ${displaySafeText(sym.name)}  (${bodyLen}\u2113)${docFirst}${statsStr}${notebookSuffix}`);
   }
   const text = guardText(staleWarning(resolved, "outline") + lines.join("\n"), "symbol");
   recordReadStat("outline", fullSourceBytes, text, opts.file);
@@ -2375,9 +2452,9 @@ function summarizeDistances(rows, weakDistance) {
   };
 }
 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}`];
+  const lines = [`Recorded semantic queries (${scope}): ${countNoun(summary.total, "query", "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.`);
+    lines.push(`${summary.total === 0 ? "None" : `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) {
@@ -2399,7 +2476,7 @@ function recordSemanticQuery(row) {
 }
 function runSemanticDistances(opts) {
   const { weak_distance: weakDistance, max_distance: maxDistance } = loadConfig().semantic;
-  const db = getGlobalDb();
+  const db = readGlobalDb();
   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 };
@@ -2407,7 +2484,7 @@ function runSemanticDistances(opts) {
 
 // src/read_semantic.ts
 init_define_import_meta_env();
-import * as fs2 from "node:fs";
+import * as fs3 from "node:fs";
 import * as path2 from "node:path";
 
 // src/semantic_merge.ts
@@ -2469,6 +2546,36 @@ function mergeNearbyHits(hits, proximity = 20) {
   return merged;
 }
 
+// src/semantic_relevance.ts
+init_define_import_meta_env();
+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 assessDenseRelevance(hits) {
+  const { max_distance: floor, weak_distance: weakDistance } = loadConfig().semantic;
+  const { kept, nearestRejected } = applyRelevanceFloor(hits, floor);
+  const closestDistance = kept.reduce((best, h) => best === null || h.distance < best ? h.distance : best, null);
+  const weakClosestDistance = closestDistance !== null && closestDistance > weakDistance ? closestDistance : null;
+  return { kept, floor, nearestRejected, closestDistance, weakDistance, weakClosestDistance };
+}
+function floorEmptiedPhrase(r) {
+  if (r.kept.length > 0 || r.nearestRejected === null) return null;
+  return `nothing within ${r.floor} (closest was ${r.nearestRejected.toFixed(3)})`;
+}
+function weakMatchPhrase(r) {
+  if (r.weakClosestDistance === null) return null;
+  return `closest was ${r.weakClosestDistance.toFixed(3)}, weak above ${r.weakDistance}`;
+}
+
 // src/read_semantic.ts
 function resolveEnclosingSymbol(filePath, chunkStartLine, chunkEndLine, linesOf) {
   const symbols = querySymbols({ filePath, limit: -1 }, globalDbPath());
@@ -2508,18 +2615,6 @@ function onlyBlankOrComment(lines, syntax) {
   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 {
@@ -2535,20 +2630,20 @@ function semanticDegradedFields(preflight, searchSemanticError) {
 }
 async function runSemantic(query, opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
-    const message = `--limit must be a positive number, got: ${opts.limit}`;
+    const message = (shown) => `--limit must be a positive number, got: ${shown}`;
     if (opts.json === true) {
-      return { text: displaySafeJson({ error: message }), code: 1 };
+      return { text: displaySafeJson({ error: message(String(opts.limit)) }), code: 1 };
     }
-    return { text: message, code: 1 };
+    return { text: message(echoedValue(String(opts.limit))), 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 (!path2.isAbsolute(opts.projectRoot) || !fs3.existsSync(opts.projectRoot) || !fs3.statSync(opts.projectRoot).isDirectory()) {
+      const message = (shown) => `projectRoot must be an absolute, existing directory, got ${shown}`;
       if (opts.json === true) {
-        return { text: displaySafeJson({ error: message }), code: 1 };
+        return { text: displaySafeJson({ error: message(opts.projectRoot) }), code: 1 };
       }
-      return { text: message, code: 1 };
+      return { text: message(echoedValue(opts.projectRoot)), code: 1 };
     }
   }
   const projectDenial = resolveProjectConfinement(opts.projectRoot).denial;
@@ -2615,7 +2710,7 @@ async function runSemantic(query, opts) {
   if (embeddingsEnabled && !deferred) {
     try {
       rawHits = await searchSemantic(
-        getDb(globalDbPath()),
+        getReadDb(globalDbPath()),
         query,
         overFetchForMerge,
         void 0,
@@ -2631,21 +2726,18 @@ async function runSemantic(query, opts) {
       }
     }
   }
-  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 relevance = assessDenseRelevance(rawHits);
+  const floorNearestRejected = relevance.nearestRejected;
+  const floorEmptied = floorEmptiedPhrase(relevance);
+  if (floorEmptied !== null) {
+    console.warn(
+      `Matching on meaning found ${floorEmptied}; these results come from keyword search alone. Raise semantic.max_distance to see weaker matches.`
+    );
   }
-  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;
+  rawHits = relevance.kept;
+  const closestDense = relevance.closestDistance;
+  const { weakDistance, weakClosestDistance } = relevance;
+  const weakPhrase = weakMatchPhrase(relevance);
   if (closestDense !== null || preflight.status === "ready" && !searchSemanticError) {
     recordSemanticQuery({ projectRoot: rootDir, closestDistance: closestDense, floorRejectedMin: floorNearestRejected, weak: weakClosestDistance !== null });
   }
@@ -2655,7 +2747,7 @@ async function runSemantic(query, opts) {
       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.`
+          `Matching on meaning found nothing, and only ${embeddedFiles} of ${countNoun(indexedFiles, "indexed file")} in this project have embeddings \u2014 these results come from keyword search alone. Run \`token-goat doctor\` for why.`
         );
       }
     } catch {
@@ -2770,9 +2862,9 @@ ${previewLines(h.previewText, 3)}`;
     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) {
+    if (weakPhrase !== 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.`
+        `Matching on meaning found nothing close for ${echoedValue(query)} (${weakPhrase}); 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);
@@ -2787,12 +2879,12 @@ ${previewLines(h.previewText, 3)}`;
     return { text: `token-goat: ${notice.trim()}`, code: 0 };
   }
   if (opts.excludeTests === true && suppressedTotal > 0) {
-    const notice = `no non-test matches for '${query}' (${excludeTestsHiddenNote(suppressedTotal)})`;
+    const hidden = excludeTestsHiddenNote(suppressedTotal);
     if (opts.json === true) {
-      const payload = { source: "fts", items: [], truncated: false, totalCount: 0, excludeTestsFilteredToEmpty: true, hint: notice };
+      const payload = { source: "fts", items: [], truncated: false, totalCount: 0, excludeTestsFilteredToEmpty: true, hint: `no non-test matches for "${query}" (${hidden})` };
       return { text: displaySafeJson(payload), code: 0 };
     }
-    return { text: `token-goat: ${notice}`, code: 0 };
+    return { text: `token-goat: no non-test matches for ${echoedValue(query)} (${hidden})`, code: 0 };
   }
   if (!anyFilter) {
     const evidenceHits = await searchEvidenceSemantically(rootDir, query, n);
@@ -2848,15 +2940,15 @@ ${previewLines(entry.text, 3)}`).join("\n\n"),
       totalCount: 0,
       ...semanticDegradedFields(preflight, searchSemanticError),
       ...!indexEmpty && isIdentifier2 ? {
-        symbolSuggestion: `token-goat symbol "${trimmedQuery2}"`,
+        symbolSuggestion: `token-goat symbol ${quotedArg(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}'`;
+  let text = indexEmpty ? `no matches for ${echoedValue(query)}
+${emptyIndexMessage(rootDir)}` : `no matches for ${echoedValue(query)}`;
   const trimmedQuery = query.trim();
   const isIdentifier = /^[A-Za-z0-9_.:-]+$/.test(trimmedQuery);
   if (!indexEmpty && isIdentifier) {
@@ -2869,11 +2961,11 @@ ${emptyIndexMessage(rootDir)}` : `token-goat: no matches for '${query}'`;
     } catch {
     }
     if (symFound) {
-      text += `
-(note: '${trimmedQuery}' is an indexed symbol name; use: token-goat symbol "${trimmedQuery}")`;
+      text += forClient(`
+(note: ${echoedValue(trimmedQuery)} is an indexed symbol name; use: ${fencedCommand("token-goat symbol " + quotedArg(trimmedQuery))})`);
     } else {
-      text += `
-Try: token-goat symbol "${trimmedQuery}"`;
+      text += forClient(`
+Try: token-goat symbol ${quotedArg(trimmedQuery)}`);
     }
   }
   if (preflight.status !== "ready") {
@@ -2898,7 +2990,7 @@ async function runSemanticMulti(queries, opts) {
       entries.push({ query, ...JSON.parse(sub.text) });
       continue;
     }
-    blocks.push(`'${query}':
+    blocks.push(`${echoedValue(query)}:
 ${sub.text}`);
   }
   return { text: opts.json === true ? displaySafeJson(entries) : blocks.join("\n\n"), code: anyOk ? 0 : 1 };
@@ -2925,7 +3017,7 @@ function renderRefLines(ref, contextLines, indent = "  ") {
   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}  `)];
+  return [base, ...renderContextWindow(displaySafeText(displayPath), ref.line, window, "", `${indent}  `)];
 }
 function withContextLines(items, contextLines) {
   if (!(contextLines > 0)) return items;
@@ -3002,27 +3094,27 @@ function refsSearchBaselineBytes(rows) {
 `, "utf8");
   return deliveredOutputBytes(total);
 }
-function renderRefsTargets(targets, opts, {
-  annotateHiddenByGrep
-}) {
+function renderRefsTargets(targets, opts) {
   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"));
+    emitErr(formatCommandError(new CliError(formatAmbiguity(qualified.symbol, qualified.file, qualified.candidates, opts.projectRoot, "refs").split("\n"))));
     return 1;
   }
   const jsonOut = {};
   let anyFound = false;
+  let anyFilteredByGrep = 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;
+    else if (opts.grep !== void 0 && preGrepCount > 0) anyFilteredByGrep = 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 } : {} });
+      const withHidden = (payload) => ({ ...payload, ...hiddenByGrep > 0 ? { hiddenByGrep } : {} });
       if (opts.top !== void 0) {
         jsonOut[key] = withHidden(topFilesJsonPayload(results, opts.top));
       } else {
@@ -3067,32 +3159,36 @@ function renderRefsTargets(targets, opts, {
     const text2 = displaySafeJson(jsonOut);
     emit(text2);
     if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text2, opts.spec);
-    return anyFound ? 0 : 1;
+    return anyFound || anyFilteredByGrep ? 0 : 1;
+  }
+  if (!anyFound && !anyFilteredByGrep) {
+    emitErr(formatCommandError(new CliError(lines)));
+    return 1;
   }
   const text = lines.join("\n");
   emitGuarded(text, "symbol");
   if (anyFound) recordReadStat("symbol_read", fullSourceBytes, text, opts.spec);
-  return anyFound ? 0 : 1;
+  return 0;
 }
 function runRefs(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
-    emitErr(`--limit must be a positive number, got: ${opts.limit}`);
+    emitErr(formatCommandError(`--limit must be a positive number, got: ${echoedValue(String(opts.limit))}`));
     return 1;
   }
   if (opts.top !== void 0 && opts.top <= 0) {
-    emitErr(`--top must be a positive number, got: ${opts.top}`);
+    emitErr(formatCommandError(`--top must be a positive number, got: ${echoedValue(String(opts.top))}`));
     return 1;
   }
   const { root: confinedRoot, denial: projectDenial } = resolveProjectConfinement(opts.projectRoot);
   if (projectDenial !== null) {
-    emitErr(projectDenial);
+    emitErr(formatCommandError(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);
+        emitErr(formatCommandError(denial));
         return 1;
       }
     }
@@ -3103,8 +3199,7 @@ function runRefs(opts) {
   if (symbols.length <= 1) return runRefsSingle(opts);
   return renderRefsTargets(
     symbols.map((symbol) => ({ file, symbol, key: symbol })),
-    opts,
-    { annotateHiddenByGrep: true }
+    opts
   );
 }
 function runRefsCrossFile(pairs, opts) {
@@ -3112,16 +3207,14 @@ function runRefsCrossFile(pairs, opts) {
   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 }
+    opts
   );
 }
 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"));
+    emitErr(formatCommandError(new CliError(formatAmbiguity(qualified.symbol, qualified.file, qualified.candidates, opts.projectRoot, "refs").split("\n"))));
     return 1;
   }
   const qualifiedDef = qualified?.kind === "ok" ? qualified.entry : void 0;
@@ -3137,29 +3230,29 @@ function runRefsSingle(opts) {
       return 0;
     }
     if (opts.excludeTests === true && suppressed > 0) {
-      emitErr(`No non-test references found for '${symName}' (${excludeTestsHiddenNote(suppressed)})`);
+      emitErr(formatCommandError(`No non-test references found for ${echoedValue(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)}`);
+      emitErr(formatCommandError(`Symbol not found: ${echoedValue(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)));
+      emitErr(formatCommandError(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));
+      emitErr(formatCommandError(refBlindKindNotice(symName, kindVerdict.blindKinds)));
       return 1;
     }
-    emitErr(`No references found for '${symName}'`);
+    emitErr(formatCommandError(`No references found for ${echoedValue(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));
@@ -3208,7 +3301,7 @@ function renderTopFilesSummary(refs, topN, suppressed) {
   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)`);
+    lines.push(forClient(`  ...(${countNoun(omittedFiles, "more file")}, ${countNoun(refs.length - shownRefs, "more reference")} elided; use a higher --top to see more)`));
   }
   return lines;
 }
@@ -3234,7 +3327,7 @@ function renderCallerGroups(refs, contextLines = 0) {
     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, "", "    "));
+      if (window !== null) lines.push(...renderContextWindow(displaySafeText(displayPath), ref.line, window, "", "    "));
     }
   }
   return lines;
@@ -3242,7 +3335,7 @@ function renderCallerGroups(refs, contextLines = 0) {
 
 // src/read_git.ts
 init_define_import_meta_env();
-import * as fs3 from "node:fs";
+import * as fs4 from "node:fs";
 import * as path3 from "node:path";
 
 // src/conflict_query.ts
@@ -3445,9 +3538,9 @@ function runConflicts(opts) {
     const abs = path3.resolve(opts.path);
     let stat;
     try {
-      stat = fs3.statSync(abs);
+      stat = fs4.statSync(abs);
     } catch {
-      emitErr(`Could not read: ${opts.path}`);
+      emitErr(formatCommandError(couldNotReadError(opts.path)));
       return 1;
     }
     files = stat.isDirectory() ? walkProject(abs).files : [abs];
@@ -3566,6 +3659,21 @@ function parseHunklessFiles(diffText) {
   return hunkless;
 }
 var EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+var CHANGED_HINT_BATCH = 512;
+function batchRowResolved(row) {
+  return row !== void 0 && /^[0-9a-f]{40,64} /.test(row);
+}
+function resolveHintRefs(cwd, ref, candidates) {
+  const batch = runGit(["cat-file", "--batch-check"], { cwd, input: `${[ref, ...candidates].join("\n")}
+` });
+  const rows = batch.stdout.split(/\r?\n/);
+  if (batch.exitCode === 0 && rows.length >= candidates.length + 1) {
+    return { refResolves: batchRowResolved(rows[0]), suggestedRef: candidates.find((_, i) => batchRowResolved(rows[i + 1])) ?? null };
+  }
+  const resolves = (name) => runGit(["rev-parse", "--verify", "--quiet", name], { cwd }).exitCode === 0;
+  if (resolves(ref)) return { refResolves: true, suggestedRef: null };
+  return { refResolves: false, suggestedRef: candidates.find((c) => resolves(c)) ?? null };
+}
 function buildChangedRefHint(cwd, ref) {
   const countResult = runGit(["rev-list", "--count", "HEAD"], { cwd });
   if (countResult.exitCode !== 0) {
@@ -3575,61 +3683,67 @@ function buildChangedRefHint(cwd, ref) {
   if (!Number.isFinite(commitCount) || commitCount < 1) {
     return null;
   }
-  const refResolves = runGit(["rev-parse", "--verify", "--quiet", ref], { cwd });
-  if (refResolves.exitCode === 0) {
+  if (/[\r\n]/.test(ref)) {
     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;
-    }
+  const candidates = [];
+  for (let n = commitCount - 1; n >= 1 && candidates.length < CHANGED_HINT_BATCH; n--) {
+    candidates.push(`HEAD~${n}`);
   }
+  const answer = resolveHintRefs(cwd, ref, candidates);
+  if (answer.refResolves) {
+    return null;
+  }
+  let suggestedRef = answer.suggestedRef;
   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}`;
+  return `Hint: this repo has only ${commitWord}; ${echoedValue(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}`);
+  emitErr(formatCommandError(`Refusing a git ref that starts with '-': ${ref}`));
 }
 function literalPathspec(file) {
   return `:(literal)${file}`;
 }
-function withRenameSources(cwd, ref, files) {
-  const wanted = new Set(files);
+function parseNameStatus(stdout) {
+  const unquote = (f) => f.startsWith('"') && f.endsWith('"') && f.length > 1 ? unquoteGitPath(f.slice(1, -1)) : f;
+  const files = [];
+  const renamedFrom = /* @__PURE__ */ new Map();
+  for (const row of stdout.split(/\r?\n/)) {
+    if (row === "") continue;
+    const cols = row.split("	");
+    const last = cols[cols.length - 1];
+    if (cols.length < 2 || last === void 0 || last === "") continue;
+    files.push(unquote(last));
+    const from = cols[1];
+    if (cols[0]?.startsWith("R") === true && cols.length === 3 && from !== void 0) renamedFrom.set(unquote(last), unquote(from));
+  }
+  return { files, renamedFrom };
+}
+function withRenameSources(files, renamedFrom) {
   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 {
+  for (const file of files) {
+    const from = renamedFrom.get(file);
+    if (from !== void 0) paths.push(from);
   }
   return paths;
 }
-function unifiedDiffOf(cwd, ref, files, extraArgs = []) {
+function unifiedDiffOf(cwd, ref, files, renamedFrom, 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);
+  const paths = withRenameSources(files, renamedFrom);
   return paths.length > files.length ? run(paths) : first;
 }
-function changedDiffBaselineBytes(cwd, ref, files) {
+function changedDiffBaselineBytes(cwd, ref, files, renamedFrom) {
   if (files.length === 0) return 0;
   try {
-    const result = unifiedDiffOf(cwd, ref, files);
+    const result = unifiedDiffOf(cwd, ref, files, renamedFrom);
     if (result.exitCode === 0) return deliveredOutputBytes(Buffer.byteLength(result.stdout, "utf8"));
   } catch {
   }
@@ -3643,25 +3757,27 @@ function runChanged(opts = {}) {
   }
   const projectDenial = opts.symbolMode === true ? resolveProjectConfinement(opts.projectRoot).denial : null;
   if (projectDenial !== null) {
-    emitErr(projectDenial);
+    emitErr(formatCommandError(projectDenial));
     return 1;
   }
   const cwd = opts.projectRoot ?? process.cwd();
-  const projectRoot = resolveProjectRoot({ project: cwd });
   let changedFiles;
+  let renamedFrom;
   try {
-    const result = runGit(["diff", ref, "--name-only"], { cwd });
+    const result = runGit(["diff", ref, "--name-status"], { cwd });
     if (result.exitCode !== 0) {
-      emitErr(`git diff failed: ${result.stderr}`);
+      emitErr(formatGitFailure("diff", result.stderr));
       const hint = buildChangedRefHint(cwd, ref);
       if (hint !== null) {
-        emitErr(hint);
+        emitErr(formatCommandError(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);
+    const listing = parseNameStatus(result.stdout);
+    changedFiles = listing.files;
+    renamedFrom = listing.renamedFrom;
   } catch {
-    emitErr(`Could not run git diff against '${ref}'`);
+    emitErr(formatCommandError(`Could not run git diff against ${echoedValue(ref)}`));
     return 1;
   }
   const emptyEnvelope = () => {
@@ -3693,19 +3809,20 @@ function runChanged(opts = {}) {
     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)`
+        `No non-test files matched --grep ${displaySafeText(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;
   }
+  const projectRoot = opts.projectRootResolved === true ? cwd : resolveProjectRoot({ project: cwd });
   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/"]);
+      const diffResult = unifiedDiffOf(projectRoot, ref, changedFiles, renamedFrom, ["--src-prefix=a/", "--dst-prefix=b/"]);
       if (diffResult.exitCode === 0) {
         hunksByFile = parseDiffHunks(diffResult.stdout);
         hunklessFiles = parseHunklessFiles(diffResult.stdout);
@@ -3741,7 +3858,7 @@ function runChanged(opts = {}) {
     recordReadStat("changed_lookup", symbolFullBytes, symbolText, ref);
     return 0;
   }
-  const fullBytes = changedDiffBaselineBytes(projectRoot, ref, changedFiles);
+  const fullBytes = changedDiffBaselineBytes(projectRoot, ref, changedFiles, renamedFrom);
   if (opts.json === true) {
     const capped = guardJsonRows(changedFiles);
     const text = displaySafeJson({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
@@ -3800,22 +3917,22 @@ function runDiff(opts) {
   try {
     diffResult = runGit(diffArgs, { cwd });
   } catch {
-    emitErr(`Could not run git diff for '${match.filePath}'`);
+    emitErr(formatCommandError(`Could not run git diff for ${echoedValue(match.filePath)}`));
     return 1;
   }
   if (diffResult.exitCode !== 0) {
-    emitErr(`git diff failed: ${diffResult.stderr}`);
+    emitErr(formatGitFailure("diff", diffResult.stderr));
     return 1;
   }
   if (diffResult.stdout.trim() === "") {
-    emit(`No changes to '${displaySafeText(match.name)}' in '${displaySafeText(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}'.`);
+    emit(`No changes to ${echoedValue(match.name)} in ${echoedValue(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))}'.`);
+    emit(`No changes to ${echoedValue(match.name)} (lines ${match.lineStart}-${match.lineEnd}) in ${echoedValue(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}.`);
     return 0;
   }
   if (opts.json === true) {
@@ -3898,15 +4015,15 @@ function runLog(opts) {
   try {
     logResult = runGit(logArgs, { cwd });
   } catch {
-    emitErr(`Could not run git log for '${match.filePath}'`);
+    emitErr(formatCommandError(`Could not run git log for ${echoedValue(match.filePath)}`));
     return 1;
   }
   if (logResult.exitCode !== 0) {
-    emitErr(`git log failed: ${displaySafeText(logResult.stderr)}`);
+    emitErr(formatGitFailure("log", 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))}'.`);
+    emit(`No history for ${echoedValue(match.name)} (lines ${match.lineStart}-${match.lineEnd}) in ${echoedValue(toDisplayPath(getDisplayRoot(opts.projectRoot), match.filePath))}.`);
     return 0;
   }
   if (opts.json === true) {
@@ -3934,14 +4051,14 @@ function runLog(opts) {
 
 // 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;
+import * as fs5 from "node:fs";
+var OPEN_FOR_STAT = process.platform === "win32" ? fs5.constants.O_RDONLY : fs5.constants.O_RDONLY | fs5.constants.O_NONBLOCK;
 function statThroughHandle(p) {
-  const fd = fs4.openSync(p, OPEN_FOR_STAT);
+  const fd = fs5.openSync(p, OPEN_FOR_STAT);
   try {
-    return fs4.fstatSync(fd, { bigint: true });
+    return fs5.fstatSync(fd, { bigint: true });
   } finally {
-    fs4.closeSync(fd);
+    fs5.closeSync(fd);
   }
 }
 
@@ -4040,8 +4157,7 @@ function createHandoff(name, text, projectRoot) {
     name,
     projectRoot: root,
     contentId: contentIdValue,
-    // Keep the handoff independently resolvable if the generic content entry
-    // is later evicted from the shared bounded cache.
+    // Keep the handoff independently resolvable if the generic content entry is later evicted from the shared bounded cache.
     text: safeText,
     createdAt: Date.now()
   };
@@ -4052,7 +4168,7 @@ function createHandoff(name, text, projectRoot) {
   });
   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}` };
+  return { id, name, contentId: contentIdValue, projectRoot: root, recovery: `token-goat handoff-resolve -- ${quotedArg(name)}` };
 }
 function resolveHandoff(name, opts = {}) {
   const root = normalizeProjectRoot(opts.projectRoot);
@@ -4077,6 +4193,9 @@ export {
   checkSemanticReadiness,
   offlineEmbedNotice,
   mergeNearbyHits,
+  assessDenseRelevance,
+  floorEmptiedPhrase,
+  weakMatchPhrase,
   runSymbol,
   runBrief,
   AMBIGUOUS_HEADING_LIMIT,