token-goat 2.9.3 → 2.9.4

package/README.md

@@ -114,6 +114,7 @@ The fastest way to reduce AI token costs is fixing these five, not writing short
 | Index-only files (lockfiles, source maps, bundles) read on every session | Pre-Read suppression for read-only files (package-lock.json, *.map, dist/), skipped unless explicitly edited |
 | Large markdown file read in full (README.md, CHANGELOG.md, CLAUDE.md ≥8 KB) | Heading tree intercepted instead — H1–H3 with `#2`/`#3` disambiguation; `token-goat section` shortcuts listed for well-known files; post-edit injects a re-read suggestion rather than the full file |
 | Subagent reads a ≥30 KB markdown file whole, on its first look at it | Off by default. Set `subagent_markdown_first_read_deny = true` under `[hints]` to block that read and answer with the heading tree instead. Only fires in a subagent, only on a first, un-ranged read of a `.md`/`.mdx`/`.markdown` file with at least three headings; a read that already asks for a line range, and every main-session read, pass through untouched |
+| A source file is read whole for the first time, with no earlier copy to compare it against | Off by default. Set `fold_code_bodies = true` under `[hints]` to keep each function's declaration and its first eight lines, replacing the rest with one line naming the symbol, the exact range removed, and the command that returns it. Comment blocks of twelve lines or more fold to their first two on the same terms. Imports, signatures, type declarations, classes and interfaces are never folded, and a file whose index no longer matches what is on disk keeps its bodies. Measured on this repository's own source: 229 of 256 files fold, and 43% of what a read of them delivers is removed. A read that already names an offset or a limit, and any file holding something that looks like a secret, pass through untouched |
 | PDF opened via Read | Full read denied; PDF shows page count and outline (`token-goat pdf-extract` pulls the actual text, optionally paged/sliced, when the outline isn't enough) |
 | Excel/PowerPoint/Word file (.xlsx/.pptx/.docx) opened via Read | Full read denied; redirects to the matching narrow-slice command family (`xlsx-sheets`/`xlsx-head`/`xlsx-range`/`xlsx-query`, `pptx-outline`/`pptx-slide`/`pptx-notes`/`pptx-text`, `docx-outline`/`docx-text`) instead of extracting the whole document as text |
 | Other Office binary (.odt, .ods, .ott, .odp) opened via Read | Full read denied; redirects to `pandoc` for text extraction (no dedicated reader for these formats yet) |
@@ -142,7 +143,7 @@ The fastest way to reduce AI token costs is fixing these five, not writing short
 | `grep`/`rg` matches a line in a `.min.js` or `.min.css` file | Matching line truncated to 200 chars; filename and line number preserved |
 | Claude Code writes async-task output to a temp file | `pre_read` intercepts the path and redirects to `token-goat bash-output <id>` with `--head`/`--tail`/`--grep` support |
 | Re-read hints fire immediately after conversation compaction | Grace period suppresses deny hints for the first few reads after a compact so the model can re-orient |
-| Large reference doc (CLAUDE.arch.md, API spec) re-read in full every new session | `token-goat compact-doc <path>` builds a deterministic extractive sidecar (headings + first N lines per section); `pre_read` serves it in place of the full file — 80–95% smaller. Sidecar is automatically marked stale when the source is edited. |
+| Large reference doc (CLAUDE.arch.md, API spec) re-read in full every new session | `token-goat compact-doc <path>` builds a deterministic extractive sidecar (headings + first N lines per section); `pre_read` serves it in place of the full file — typically 60–95% smaller (median 67% across this repo's own docs). Sidecar is automatically marked stale when the source is edited. |
 | Re-read denial fires as an advisory hint the model can ignore | When `deny_reread` is on (default), `pre_read` actively denies re-reads of files confirmed in the current context window, not just nudges; the advisory still fires for older reads that may have scrolled out |
 | Unchanged files produce duplicate hints across sessions | Hint fingerprint includes file path; unchanged-file short-circuit skips re-read pre-check entirely |
 | Bash dedup hints conflict with other compression | `token-goat compress` can be called as dedup-vs-hint filter; one-call access to cached output |

package/dist/{token-goat-chunk-KKHKXUVS.mjs → token-goat-chunk-3ZR4NLB3.mjs}

@@ -12,7 +12,7 @@ init_define_import_meta_env();
 import { createRequire } from "node:module";
 function resolveVersion() {
   if (true) {
-    return "2.9.3";
+    return "2.9.4";
   }
   const require2 = createRequire(import.meta.url);
   const pkg = require2("../package.json");
@@ -2273,6 +2273,8 @@ var CONFIG_DEFAULTS = {
     // existing users -- see the reread_deny/reread_deny_min_bytes fix's commit message.
     reread_deny_min_bytes: 51200,
     stable_doc_compacts: true,
+    // Off until measured. This one rewrites what the model reads on a FIRST look at a source file, where -- unlike every re-read mechanism beside it -- the reader has no prior copy to notice an omission against. Its restore rate and edit-error delta cannot be observed until it has run, so the honest default is the one that changes nothing.
+    fold_code_bodies: false,
     truncated_read_min_lines: 200,
     protect_recent_reads: 4,
     warn_unbalanced_shell_quoting: true,
@@ -2607,6 +2609,8 @@ var PROJECT_LOCKED_SECTIONS = [
   "screenshot"
 ];
 var PROJECT_LOCKED_KEYS = [
+  // A repository must not be able to decide how much of its own source an agent gets to see. Turning this on folds function bodies out of every Read of this project's files, so a checked-in `.token-goat.toml` setting it true would shrink what a reviewing agent is shown of the very code it came to review -- and the fold is silent about intent, so it reads as normal output. The user's own global config and TOKEN_GOAT_FOLD_CODE_BODIES still set it freely; only the project-supplied layer is refused.
+  "hints.fold_code_bodies",
   "image_shrink.max_image_pixels",
   "indexing.cross_project_symbols",
   "worker.blocked_roots"
@@ -3019,6 +3023,7 @@ function _buildConfig(raw, projectRaw = {}) {
   hi.reread_deny = validatedBool(hi_raw["reread_deny"], hi.reread_deny);
   hi.reread_deny_min_bytes = validatedIntWithLegacySentinel(hi_raw["reread_deny_min_bytes"], hi.reread_deny_min_bytes, 2048, ...boundsOf("hints.reread_deny_min_bytes"));
   hi.stable_doc_compacts = validatedBool(hi_raw["stable_doc_compacts"], hi.stable_doc_compacts);
+  hi.fold_code_bodies = validatedBool(hi_raw["fold_code_bodies"], hi.fold_code_bodies);
   hi.truncated_read_min_lines = validatedInt(hi_raw["truncated_read_min_lines"], hi.truncated_read_min_lines, ...boundsOf("hints.truncated_read_min_lines"));
   hi.protect_recent_reads = validatedInt(hi_raw["protect_recent_reads"], hi.protect_recent_reads, ...boundsOf("hints.protect_recent_reads"));
   hi.warn_unbalanced_shell_quoting = validatedBool(hi_raw["warn_unbalanced_shell_quoting"], hi.warn_unbalanced_shell_quoting);
@@ -3047,6 +3052,7 @@ function _buildConfig(raw, projectRaw = {}) {
   hi.min_file_lines_for_hint = envInt("TOKEN_GOAT_MIN_FILE_LINES_FOR_HINT", hi.min_file_lines_for_hint, ...boundsOf("hints.min_file_lines_for_hint"));
   hi.git_hint_max_ms = envInt("TOKEN_GOAT_GIT_HINT_MAX_MS", hi.git_hint_max_ms, ...boundsOf("hints.git_hint_max_ms"));
   hi.stable_doc_compacts = envBool("TOKEN_GOAT_STABLE_DOC_COMPACTS", hi.stable_doc_compacts);
+  hi.fold_code_bodies = envBool("TOKEN_GOAT_FOLD_CODE_BODIES", hi.fold_code_bodies);
   hi.context_threshold_advisory = envBool("TOKEN_GOAT_CONTEXT_THRESHOLD_ADVISORY", hi.context_threshold_advisory);
   hi.pre_skill_advisory = envBool("TOKEN_GOAT_PRE_SKILL_ADVISORY", hi.pre_skill_advisory);
   hi.quiet_hours = envStr("TOKEN_GOAT_QUIET_HOURS", hi.quiet_hours);
@@ -3214,6 +3220,7 @@ var CONFIG_KEY_ENV_OVERRIDES = {
   "hints.min_file_lines_for_hint": ["TOKEN_GOAT_MIN_FILE_LINES_FOR_HINT"],
   "hints.git_hint_max_ms": ["TOKEN_GOAT_GIT_HINT_MAX_MS"],
   "hints.stable_doc_compacts": ["TOKEN_GOAT_STABLE_DOC_COMPACTS"],
+  "hints.fold_code_bodies": ["TOKEN_GOAT_FOLD_CODE_BODIES"],
   "hints.context_threshold_advisory": ["TOKEN_GOAT_CONTEXT_THRESHOLD_ADVISORY"],
   "hints.pre_skill_advisory": ["TOKEN_GOAT_PRE_SKILL_ADVISORY"],
   "hints.quiet_hours": ["TOKEN_GOAT_QUIET_HOURS"],
@@ -3352,6 +3359,7 @@ function saveConfig(config) {
       reread_deny: config.hints.reread_deny,
       reread_deny_min_bytes: config.hints.reread_deny_min_bytes,
       stable_doc_compacts: config.hints.stable_doc_compacts,
+      fold_code_bodies: config.hints.fold_code_bodies,
       truncated_read_min_lines: config.hints.truncated_read_min_lines,
       protect_recent_reads: config.hints.protect_recent_reads,
       prompt_triggers: config.hints.prompt_triggers,
@@ -6002,6 +6010,7 @@ var _KIND_GROUPS = [
       "browser_tab_dedup",
       "grep:fold",
       "read:served_elide",
+      "read:body_fold",
       "handoff_create",
       "handoff_resolve",
       "plan_echo_collapse"
@@ -6447,6 +6456,8 @@ var KIND_TO_SOURCE = {
   // with real bytes removed from it. Filing it under the advisory bucket would add non-hint
   // savings to hint_stats.ts's savedBytes, which reads by_source[SOURCE_HINT] wholesale.
   "read:served_elide": SOURCE_CONTENT,
+  // Same bucket and same reasoning as read:served_elide directly above: a rewrite of a Read that did happen, with real bytes removed, not an advisory about whether to read at all.
+  "read:body_fold": SOURCE_CONTENT,
   content_retrieve: SOURCE_CONTENT,
   handoff_create: SOURCE_CONTENT,
   handoff_resolve: SOURCE_CONTENT

package/dist/{token-goat-chunk-LLNA42NI.mjs → token-goat-chunk-5BHXZEOI.mjs}

@@ -3,7 +3,7 @@ const require = __cjsRequire(import.meta.url);
 import {
   deliveredOutputBytes,
   wrappedShell
-} from "./token-goat-chunk-OKJX2JWW.mjs";
+} from "./token-goat-chunk-EPX5DWGM.mjs";
 import {
   ToolFilter,
   capTokens,
@@ -15,7 +15,7 @@ import {
   recordStat,
   selectFilter,
   shlexSplit
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
 import {
   init_define_import_meta_env

package/dist/{token-goat-chunk-2VVXTAGD.mjs → token-goat-chunk-63XEQMNU.mjs}

@@ -18,7 +18,7 @@ import {
   storeWebOutput,
   summarizeResidentContext,
   taskListPruneHint
-} from "./token-goat-chunk-A4VBNWSL.mjs";
+} from "./token-goat-chunk-FSC44QOH.mjs";
 import {
   BASH_OUTPUT_SUBDIR,
   UNTRUSTED_TOOL_TAG,
@@ -112,11 +112,11 @@ import {
   wasCliReadThisSession,
   wasFileReadThisSession,
   wasHintShown
-} from "./token-goat-chunk-3XVGPLDS.mjs";
+} from "./token-goat-chunk-CBO45DYZ.mjs";
 import {
   canRunWrappedShell,
   deliveredOutputBytes
-} from "./token-goat-chunk-OKJX2JWW.mjs";
+} from "./token-goat-chunk-EPX5DWGM.mjs";
 import {
   BODY_FIRST_TOOL_RESPONSE_KEYS,
   ENV_KEYS,
@@ -173,7 +173,7 @@ import {
   splitOwnTrailingNotices,
   stripAnsiEscapes,
   toKB
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import {
   init_define_import_meta_env
 } from "./token-goat-chunk-A37V4PBF.mjs";
@@ -703,7 +703,7 @@ init_define_import_meta_env();
 var TRACKED_SKILL = "token-goat";
 var MAX_COMMANDS_SHOWN = 8;
 async function currentCommandNames() {
-  const { buildProgram } = await import("./token-goat-chunk-XSSQFI4C.mjs");
+  const { buildProgram } = await import("./token-goat-chunk-GEXHIIKM.mjs");
   return flattenCommandNames(buildCommandManifest(buildProgram()));
 }
 async function recordSkillVersionSnapshot(sessionId, skillName) {

package/dist/{token-goat-chunk-6FQMEMWX.mjs → token-goat-chunk-6MU6FHE3.mjs}

@@ -86,7 +86,7 @@ import {
   runZipRead,
   symbolNamesInFile,
   upsertNote
-} from "./token-goat-chunk-7A7SBE6R.mjs";
+} from "./token-goat-chunk-US57I7GN.mjs";
 import {
   DEFAULT_RECONCILE_BUDGET_MS,
   GEMINI_TOOL_NAME_MAP,
@@ -108,7 +108,7 @@ import {
   runReconcile,
   storeWebOutput,
   summarizeResidentContext
-} from "./token-goat-chunk-A4VBNWSL.mjs";
+} from "./token-goat-chunk-FSC44QOH.mjs";
 import {
   AGENT_SALT_MARKER,
   BASH_OUTPUT_SUBDIR,
@@ -175,6 +175,7 @@ import {
   getFileEntry,
   getHintStatsSummary,
   getHintStatsTotals,
+  getParserFreshness,
   getProjectIndexCounts,
   getSessionFiles,
   getSessionId,
@@ -193,6 +194,7 @@ import {
   isHintCategory,
   isParseSkipEligible,
   isRecallCacheType,
+  isSuppressionCategory,
   isWorkerRunning,
   listBlobs,
   listOutputs,
@@ -238,7 +240,7 @@ import {
   visionTokensSavedByText,
   walkProject,
   writeCompact
-} from "./token-goat-chunk-3XVGPLDS.mjs";
+} from "./token-goat-chunk-CBO45DYZ.mjs";
 import {
   C,
   CONFIG_KEY_ENV_OVERRIDES,
@@ -364,7 +366,7 @@ import {
   withFileLock,
   withRetryOnLock,
   writeJsonSettings
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import {
   __export,
   init_define_import_meta_env
@@ -6219,6 +6221,38 @@ function checkEmbeddingCoverage(dbPath, rootDir) {
     };
   }
 }
+var PARSER_FRESHNESS_WARN_FRACTION = 0.25;
+function checkParserFreshness(dbPath, rootDir) {
+  if (!fs12.existsSync(dbPath)) {
+    return { name: "Parser freshness", status: "ok", message: "no database yet" };
+  }
+  try {
+    const { indexedFiles, currentFiles } = getParserFreshness(dbPath, PARSER_FINGERPRINT, rootDir);
+    if (indexedFiles === 0) {
+      return { name: "Parser freshness", status: "ok", message: "no indexed files yet" };
+    }
+    const stale = indexedFiles - currentFiles;
+    const pct3 = Math.round(stale / indexedFiles * 100);
+    if (currentFiles / indexedFiles < 1 - PARSER_FRESHNESS_WARN_FRACTION) {
+      return {
+        name: "Parser freshness",
+        status: "warn",
+        message: `${stale} of ${indexedFiles} indexed file(s) (${pct3}%) were parsed by a different build of the extraction logic, so their symbols are whatever that build extracted \u2014 'symbol', 'read', 'outline' and 'skeleton' answer from those rows, and the read-hook body fold declines on them. Run 'token-goat index' in this project to reparse them; --force is not needed, a parser mismatch reindexes on its own`
+      };
+    }
+    return {
+      name: "Parser freshness",
+      status: "ok",
+      message: `${currentFiles} of ${indexedFiles} indexed file(s) match the running parser`
+    };
+  } catch (err2) {
+    return {
+      name: "Parser freshness",
+      status: "warn",
+      message: `could not query parser freshness: ${extractErrorMessage(err2)}`
+    };
+  }
+}
 var DIRTY_QUEUE_BACKLOG_WARN_THRESHOLD = 500;
 function checkDirtyQueueHealth(dataDir2) {
   let pendingCount = 0;
@@ -6454,6 +6488,7 @@ var LOCKED_BOOLEAN_SAFE_VALUE = {
   "screenshot.block_private_targets": true,
   "network.offline": true,
   "indexing.cross_project_symbols": false,
+  "hints.fold_code_bodies": false,
   "webfetch.compress_bodies": true
 };
 function lockedEnvOverridableKeys() {
@@ -6656,6 +6691,7 @@ function runDoctor(dataDir2, configPath2, rootDir, processes) {
   results.push(checkConfigValid(actualConfigPath));
   results.push(checkEmbeddings(loadConfig(rootDir)));
   results.push(checkEmbeddingCoverage(path12.join(actualDataDir, "global.db"), rootDir));
+  results.push(checkParserFreshness(path12.join(actualDataDir, "global.db"), rootDir));
   for (const result of checkSecurityPosture(loadConfig(rootDir), actualDataDir)) results.push(result);
   results.push(checkDiskSpace(actualDataDir));
   const copilotResult = checkCopilotCli(copilotCliConfigPath(), copilotCliScriptPath());
@@ -15286,15 +15322,18 @@ function suppressedCell(row) {
   if (!row.suppressed) return "no";
   return row.suppressionPermanent ? "yes (permanent)" : "yes";
 }
+function efficacyCell(row) {
+  const pct3 = row.efficacyPct === null ? "n/a" : `${row.efficacyPct}%`;
+  return isSuppressionCategory(row.category) ? `${pct3} *` : pct3;
+}
 function printSummary(rows) {
   const w = (text) => {
     process.stdout.write(text);
   };
-  w(pad("category", 22) + pad("emitted", 9) + pad("acted-on", 10) + pad("efficacy", 10) + pad("suppressed", 17) + pad("manual+", 9) + pad("manual-", 9) + "spent\n");
+  w(pad("category", 22) + pad("emitted", 9) + pad("acted-on", 10) + pad("efficacy", 12) + pad("suppressed", 17) + pad("manual+", 9) + pad("manual-", 9) + "spent\n");
   for (const row of rows) {
-    const pct3 = row.efficacyPct === null ? "n/a" : `${row.efficacyPct}%`;
     w(
-      pad(row.category, 22) + pad(String(row.emitted), 9) + pad(String(row.actedOn), 10) + pad(pct3, 10) + pad(suppressedCell(row), 17) + pad(String(row.manualEffective), 9) + pad(String(row.manualIneffective), 9) + formatSpentCell(row) + "\n"
+      pad(row.category, 22) + pad(String(row.emitted), 9) + pad(String(row.actedOn), 10) + pad(efficacyCell(row), 12) + pad(suppressedCell(row), 17) + pad(String(row.manualEffective), 9) + pad(String(row.manualIneffective), 9) + formatSpentCell(row) + "\n"
     );
   }
 }
@@ -15335,6 +15374,11 @@ function runHintStatsCommand(opts = {}) {
     process.stdout.write("No hint emissions recorded yet \u2014 the zeros below are absence of data, not measured ineffectiveness.\n");
   }
   printSummary(rows);
+  if (rows.some((r) => isSuppressionCategory(r.category) && r.emitted > 0)) {
+    process.stdout.write(
+      '\n* Scored on an absence: these hints ask the agent NOT to do something, so a window that expires with no re-read counts as compliance. Their percentage is not comparable with the unmarked rows, which only count when the agent runs the command the hint named. A high starred figure means "the warned-against read was not seen", not "this hint persuaded anyone".\n'
+    );
+  }
   const permanent = rows.filter((r) => r.suppressionPermanent);
   if (permanent.length > 0) {
     const names = permanent.map((r) => r.category).join(", ");
@@ -15667,7 +15711,7 @@ async function cmdMcpServe() {
   let StdioServerTransport;
   try {
     ;
-    ({ createMcpServer } = await import("./token-goat-chunk-3UBORD6Z.mjs"));
+    ({ createMcpServer } = await import("./token-goat-chunk-OZAEJQ7L.mjs"));
     ({ StdioServerTransport } = await import("./token-goat-chunk-EVC4TOLE.mjs"));
   } catch (err2) {
     process.stderr.write(
@@ -15692,7 +15736,7 @@ async function cmdHook(event, opts) {
   if (typeof opts.harness === "string" && opts.harness.length > 0) {
     process.env[ENV_KEYS.HARNESS_OVERRIDE] = opts.harness;
   }
-  const { relay } = await import("./token-goat-chunk-HC5NMGPD.mjs");
+  const { relay } = await import("./token-goat-chunk-EQKNR7CN.mjs");
   await relay(event);
 }
 async function cmdInstall(opts) {
@@ -16626,7 +16670,7 @@ function emitExtraFileArgsNote(command, first, extras, opts = {}) {
 }
 async function cmdCompress(opts) {
   try {
-    const bashRunner = await import("./token-goat-chunk-LLNA42NI.mjs");
+    const bashRunner = await import("./token-goat-chunk-5BHXZEOI.mjs");
     if (opts.compress === false) {
       process.exitCode = bashRunner.runRaw(opts.cmd, parseTimeout(opts.timeout, bashRunner.DEFAULT_TIMEOUT_SECONDS));
       return;

package/dist/{token-goat-chunk-3XVGPLDS.mjs → token-goat-chunk-CBO45DYZ.mjs}

@@ -96,7 +96,7 @@ import {
   toDisplayPath,
   toKB,
   withFileLock
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import {
   registerReset
 } from "./token-goat-chunk-EEIDFMEM.mjs";
@@ -6057,6 +6057,18 @@ function getEmbeddingCoverage(dbPath, rootDir) {
     embeddedFiles: countScoped("SELECT COUNT(DISTINCT file_path) as c FROM chunks", "file_path")
   };
 }
+function getParserFreshness(dbPath, parserSha, rootDir) {
+  const db = getDb(dbPath);
+  const count = (extra, params) => {
+    if (rootDir === void 0) {
+      return db.prepare(`SELECT COUNT(*) as c FROM files${extra === "" ? "" : ` WHERE ${extra}`}`).get(...params).c;
+    }
+    const scope = projectScopeClause("path");
+    const where = extra === "" ? scope.clause : `${scope.clause} AND ${extra}`;
+    return db.prepare(`SELECT COUNT(*) as c FROM files WHERE ${where}`).get(...scope.params(rootDir), ...params).c;
+  };
+  return { indexedFiles: count("", []), currentFiles: count("parser_sha = ?", [parserSha]) };
+}
 function isIndexEmptyForProject(dbPath, rootDir) {
   if (!fs4.existsSync(dbPath)) return true;
   try {
@@ -11081,6 +11093,10 @@ function _pathPriorityPenalty(filePath) {
   return 0;
 }
 
+// src/parser_fingerprint.ts
+init_define_import_meta_env();
+var PARSER_FINGERPRINT = "4659c517f042a452";
+
 // src/hooks_read.ts
 init_define_import_meta_env();
 import * as fs17 from "node:fs";
@@ -12703,6 +12719,120 @@ function getOrCreateSidecar(rawBytes, cacheRoot, opts = {}) {
   return [sidecarPath, true];
 }
 
+// src/code_fold.ts
+init_define_import_meta_env();
+var FOLDABLE_KINDS = /* @__PURE__ */ new Set(["function", "method", "func", "def", "fn", "procedure", "constructor", "variable"]);
+var MIN_FOLDED_ROWS = 3;
+function planBodyFolds(rows, spans, keep, minSpan) {
+  if (rows.length === 0 || spans.length === 0 || keep < 1) return [];
+  const rowAt = /* @__PURE__ */ new Map();
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    if (row !== void 0) rowAt.set(row.no, i);
+  }
+  const ordered = [...spans].sort((a, b) => a.lineStart - b.lineStart || b.lineEnd - a.lineEnd);
+  const folds = [];
+  let foldedThrough = -1;
+  for (const span of ordered) {
+    if (!FOLDABLE_KINDS.has(span.kind)) continue;
+    if (span.lineEnd - span.lineStart + 1 < minSpan) continue;
+    if (span.lineStart <= foldedThrough) continue;
+    const firstFolded = span.lineStart + keep;
+    if (firstFolded > span.lineEnd) continue;
+    let startIdx = -1;
+    let endIdx = -1;
+    for (let line = firstFolded; line <= span.lineEnd; line++) {
+      const idx = rowAt.get(line);
+      if (idx === void 0) continue;
+      if (startIdx < 0) startIdx = idx;
+      endIdx = idx;
+    }
+    if (startIdx < 0 || endIdx < startIdx) continue;
+    const len = endIdx - startIdx + 1;
+    const firstRow = rows[startIdx];
+    const lastRow = rows[endIdx];
+    if (firstRow === void 0 || lastRow === void 0) continue;
+    if (lastRow.no - firstRow.no + 1 !== len) continue;
+    if (len < MIN_FOLDED_ROWS) continue;
+    folds.push({ startIdx, len, name: span.name, kind: "body", firstLine: firstRow.no, lastLine: lastRow.no });
+    foldedThrough = span.lineEnd;
+  }
+  return folds;
+}
+var SLASH_STAR = { line: ["//"], open: "/*", close: "*/" };
+var HASH = { line: ["#"] };
+var DOUBLE_DASH = { line: ["--"] };
+var COMMENT_SYNTAX = new Map([
+  ...["ts", "tsx", "js", "jsx", "mjs", "cjs", "java", "c", "h", "cc", "cpp", "hpp", "cs", "go", "rs", "swift", "kt", "scala", "php", "dart"].map(
+    (ext) => [ext, SLASH_STAR]
+  ),
+  ...["py", "rb", "sh", "bash", "zsh", "pl", "r"].map((ext) => [ext, HASH]),
+  ...["sql", "lua", "hs"].map((ext) => [ext, DOUBLE_DASH])
+]);
+function commentSyntaxFor(path26) {
+  const dot = path26.lastIndexOf(".");
+  if (dot < 0) return null;
+  return COMMENT_SYNTAX.get(path26.slice(dot + 1).toLowerCase()) ?? null;
+}
+function planCommentFolds(rows, syntax, commentKeep, commentMinBlock, occupied) {
+  if (syntax === null || rows.length === 0 || commentKeep < 1 || commentMinBlock < 1) return [];
+  const folds = [];
+  let i = 0;
+  let inBlock = false;
+  while (i < rows.length) {
+    const start = i;
+    while (i < rows.length) {
+      const text = rows[i]?.text ?? "";
+      const trimmed = text.trim();
+      if (inBlock) {
+        if (syntax.close !== void 0 && trimmed.includes(syntax.close)) inBlock = false;
+        i++;
+        continue;
+      }
+      if (syntax.open !== void 0 && trimmed.startsWith(syntax.open)) {
+        if (syntax.close === void 0 || !trimmed.slice(syntax.open.length).includes(syntax.close)) inBlock = true;
+        i++;
+        continue;
+      }
+      if (syntax.line.some((p) => trimmed.startsWith(p))) {
+        i++;
+        continue;
+      }
+      break;
+    }
+    const runLen = i - start;
+    if (runLen >= commentMinBlock) {
+      const foldStart = start + commentKeep;
+      const len = i - foldStart;
+      const firstRow = rows[foldStart];
+      const lastRow = rows[i - 1];
+      if (len >= MIN_FOLDED_ROWS && firstRow !== void 0 && lastRow !== void 0 && lastRow.no - firstRow.no + 1 === len) {
+        let clear = true;
+        for (let k = foldStart; k < i; k++) {
+          if (occupied.has(k)) {
+            clear = false;
+            break;
+          }
+        }
+        if (clear) folds.push({ startIdx: foldStart, len, name: "comment", kind: "comment", firstLine: firstRow.no, lastLine: lastRow.no });
+      }
+    }
+    if (i === start) i++;
+  }
+  return folds;
+}
+function mergeFolds(body, comment) {
+  const merged = [...body, ...comment].sort((a, b) => a.startIdx - b.startIdx || b.len - a.len);
+  const out = [];
+  let through = -1;
+  for (const fold of merged) {
+    if (fold.startIdx <= through) continue;
+    out.push(fold);
+    through = fold.startIdx + fold.len - 1;
+  }
+  return out;
+}
+
 // src/hooks_read.ts
 function isTsConfigFile(basename12) {
   const lower = basename12.toLowerCase();
@@ -12757,6 +12887,15 @@ function readIntToolInput(event, key) {
   }
   return void 0;
 }
+function readStartLine(event) {
+  const resp = event.raw["tool_response"];
+  if (resp === null || typeof resp !== "object") return 1;
+  const file = resp["file"];
+  if (file === null || typeof file !== "object") return 1;
+  const start = file["startLine"];
+  if (typeof start === "number" && Number.isSafeInteger(start) && start >= 1) return start;
+  return 1;
+}
 var SLICE_ESTIMATE_SCAN_CAP_BYTES = 2 * 1024 * 1024;
 var NEAR_SINGLE_LINE_SCAN_THRESHOLD = 20;
 function scanRequestedSlice(absPath, offset, limit) {
@@ -13046,7 +13185,8 @@ function preReadHandlerInner(event) {
     } catch {
     }
   }
-  if (event.toolName !== "Grep" && loadConfig().hints.stable_doc_compacts && _isDocFile(normalized)) {
+  const compactUnrangedRead = readIntToolInput(event, "offset") === void 0 && readIntToolInput(event, "limit") === void 0;
+  if (event.toolName !== "Grep" && compactUnrangedRead && loadConfig().hints.stable_doc_compacts && _isDocFile(normalized)) {
     const compactPath = compactPathFor(normalized);
     if (isCompactFresh(compactPath, normalized)) {
       const compactBody = readCompactBody(compactPath);
@@ -13056,7 +13196,7 @@ function preReadHandlerInner(event) {
         const savedBytes = counterfactualCredit(fullSize, compactBody.length);
         recordStat("session_hint", savedBytes, savedTokensFromBytes(savedBytes));
         return denyOutput(
-          "Serving the extractive compact sidecar in place of the full file (source unchanged since the last `compact-doc` build):\n\n" + fenceUntrustedFileContent(compactBody) + '\n\nUse `token-goat compact-doc "' + shown + '" --force` to rebuild it, or `token-goat compact-doc "' + shown + '" --show` to view it directly. ' + editAnywayHint(normalized)
+          "Serving the extractive compact sidecar in place of the full file (source unchanged since the last `compact-doc` build):\n\n" + fenceUntrustedFileContent(compactBody) + '\n\nThis is a lossy extract, not the whole file: front matter and any prose before the first heading are dropped entirely, each section is cut to its opening sentences, and long code fences are truncated. If you need content it left out, re-read with offset/limit for a line window, or `token-goat section "' + shown + '::Heading"` for one section in full. Use `token-goat compact-doc "' + shown + '" --force` to rebuild it, or `token-goat compact-doc "' + shown + '" --show` to view it directly. ' + editAnywayHint(normalized)
         );
       }
     }
@@ -13521,7 +13661,7 @@ function alreadyServedOutputId(event, normalized) {
     return null;
   }
 }
-function recordReadAsServedOutput(event) {
+function recordReadAsServedOutput(event, deliveredRaw = null) {
   try {
     const cfg = loadConfig().bash_compress;
     if (!cfg.enabled) return;
@@ -13531,7 +13671,7 @@ function recordReadAsServedOutput(event) {
     if (isImagePath(normalized)) return;
     const respText = extractReadOutput(event.raw);
     if (respText.includes("[Truncated:") || respText.includes("Truncated: PARTIAL view")) return;
-    const served = readWindowFromDisk(event, normalized);
+    const served = deliveredRaw ?? readWindowFromDisk(event, normalized);
     if (served === null) return;
     if (Buffer.byteLength(served, "utf-8") < Math.max(cfg.cache_min_bytes, IDENTICAL_READ_MIN_BODY_BYTES)) return;
     const id = storeBashOutputSync("Read " + normalized, served, 0, getCwd(event) ?? process.cwd());
@@ -13540,7 +13680,7 @@ function recordReadAsServedOutput(event) {
   }
 }
 var READ_NUMBERED_ROW_RE = /^\s*(\d+)[\t→](.*)$/;
-function parseNumberedReadResult(respText) {
+function parseNumberedReadResult(respText, firstLine = 1) {
   const lines2 = respText.split("\n");
   const header = [];
   const rows = [];
@@ -13565,7 +13705,10 @@ function parseNumberedReadResult(respText) {
     rows.push({ no: prev.no + 1, text: m[2] ?? "", raw: line });
   }
   for (; i < lines2.length; i++) trailer.push(lines2[i] ?? "");
-  return rows.length > 0 ? { header, rows, trailer } : null;
+  if (rows.length > 0) return { header, rows, trailer };
+  if (respText === "") return null;
+  const plain = lines2.map((text, idx) => ({ no: firstLine + idx, text, raw: text }));
+  return { header: [], rows: plain, trailer: [] };
 }
 var SERVED_RUN_COMPARISON_BUDGET = 4e5;
 var SERVED_RUN_ANCHORS_PER_LINE = 32;
@@ -13620,7 +13763,7 @@ function elideAlreadyServedLines(event, respText) {
   if (respText.includes("[Truncated:") || respText.includes("Truncated: PARTIAL view")) return null;
   const ids = getFileServedOutputs(normalized);
   if (ids.length === 0) return null;
-  const parsed = parseNumberedReadResult(respText);
+  const parsed = parseNumberedReadResult(respText, readStartLine(event));
   if (parsed === null) return null;
   if (redactSecrets(respText).count > 0) return null;
   const bodies = [];
@@ -13694,11 +13837,91 @@ function elideAlreadyServedLines(event, respText) {
   }
   return emitRewrite(rewritten, "read", { kind: "read:served_elide", originalBytes });
 }
+var BODY_FOLD_KEEP_LINES = 8;
+var BODY_FOLD_MIN_SPAN = 20;
+var COMMENT_FOLD_KEEP_LINES = 2;
+var COMMENT_FOLD_MIN_BLOCK = 12;
+var BODY_FOLD_SYMBOL_LIMIT = 1e4;
+function bodyFoldNotice(name, firstLine, lastLine, shownPath) {
+  const n = lastLine - firstLine + 1;
+  return `... ${n} more lines of ${name} (${firstLine}-${lastLine}) folded -- token-goat read "${shownPath}::${name}"`;
+}
+function commentFoldNotice(firstLine, lastLine, shownPath) {
+  const n = lastLine - firstLine + 1;
+  return `... ${n} more comment lines (${firstLine}-${lastLine}) folded -- Read "${shownPath}" with offset=${firstLine}, limit=${n}`;
+}
+function foldCodeBodies(event, respText) {
+  if (!loadConfig().hints.fold_code_bodies) return null;
+  const filePath = getFilePath(event);
+  if (filePath === void 0) return null;
+  const normalized = normalizePath(filePath);
+  if (isImagePath(normalized)) return null;
+  if (readIntToolInput(event, "offset") !== void 0 || readIntToolInput(event, "limit") !== void 0) return null;
+  if (respText.includes("[Truncated:") || respText.includes("Truncated: PARTIAL view")) return null;
+  if (redactSecrets(respText).count > 0) return null;
+  const parsed = parseNumberedReadResult(respText, readStartLine(event));
+  if (parsed === null) return null;
+  let spans = [];
+  try {
+    const entry = getFileEntry(normalized);
+    if (entry !== null && entry.sha !== "" && entry.sha === fingerprintFile(normalized) && entry.parserSha === PARSER_FINGERPRINT) {
+      spans = querySymbols({ filePath: normalized, limit: BODY_FOLD_SYMBOL_LIMIT });
+    }
+  } catch {
+    spans = [];
+  }
+  const bodyFolds = planBodyFolds(parsed.rows, spans, BODY_FOLD_KEEP_LINES, BODY_FOLD_MIN_SPAN);
+  const claimed = /* @__PURE__ */ new Set();
+  for (const fold of bodyFolds) for (let i = fold.startIdx; i < fold.startIdx + fold.len; i++) claimed.add(i);
+  const commentFolds = planCommentFolds(
+    parsed.rows,
+    commentSyntaxFor(normalized),
+    COMMENT_FOLD_KEEP_LINES,
+    COMMENT_FOLD_MIN_BLOCK,
+    claimed
+  );
+  const folds = mergeFolds(bodyFolds, commentFolds);
+  if (folds.length === 0) return null;
+  const shown = displaySafePath(normalized);
+  const out = [...parsed.header];
+  const rawOut = [];
+  let at = 0;
+  for (const fold of folds) {
+    for (let i = at; i < fold.startIdx; i++) {
+      out.push(parsed.rows[i]?.raw ?? "");
+      rawOut.push(parsed.rows[i]?.text ?? "");
+    }
+    out.push(fold.kind === "comment" ? commentFoldNotice(fold.firstLine, fold.lastLine, shown) : bodyFoldNotice(fold.name, fold.firstLine, fold.lastLine, shown));
+    at = fold.startIdx + fold.len;
+  }
+  for (let i = at; i < parsed.rows.length; i++) {
+    out.push(parsed.rows[i]?.raw ?? "");
+    rawOut.push(parsed.rows[i]?.text ?? "");
+  }
+  out.push(...parsed.trailer);
+  const rewritten = out.join("\n");
+  const originalBytes = Buffer.byteLength(respText, "utf-8");
+  if (!isRewriteWorthwhile({
+    originalBytes,
+    rewrittenBytes: Buffer.byteLength(rewritten, "utf-8"),
+    noticeBytes: 0,
+    minNetSavingsBytes: resolveMinNetSavingsBytes()
+  })) {
+    return null;
+  }
+  return {
+    output: emitRewrite(rewritten, "read", { kind: "read:body_fold", originalBytes }),
+    deliveredRaw: rawOut.join("\n")
+  };
+}
 function postReadHandler(event) {
-  const elided = elideAlreadyServedLines(event, extractReadOutput(event.raw));
-  const out = applyHintTracking(event, postReadHandlerInner(event, elided !== null), classifyReadHint);
-  recordReadAsServedOutput(event);
-  return elided ?? out;
+  const respText = extractReadOutput(event.raw);
+  const elided = elideAlreadyServedLines(event, respText);
+  const folded = elided === null ? foldCodeBodies(event, respText) : null;
+  const rewrite = elided ?? folded?.output ?? null;
+  const out = applyHintTracking(event, postReadHandlerInner(event, rewrite !== null), classifyReadHint);
+  recordReadAsServedOutput(event, folded?.deliveredRaw ?? null);
+  return rewrite ?? out;
 }
 registerHook("post_tool_use", postReadHandler, { toolName: "Read" });
 
@@ -14521,10 +14744,6 @@ function getTrackedFiles(cwd = process.cwd()) {
   }
 }
 
-// src/parser_fingerprint.ts
-init_define_import_meta_env();
-var PARSER_FINGERPRINT = "4659c517f042a452";
-
 // src/parser.ts
 init_define_import_meta_env();
 import * as fs22 from "node:fs";
@@ -21387,12 +21606,14 @@ export {
   detectWalkMode,
   getProjectIndexCounts,
   getEmbeddingCoverage,
+  getParserFreshness,
   isIndexEmptyForProject,
   emptyIndexMessage,
   isHintCategory,
   classifyBashHint,
   classifyEditHint,
   applyHintTracking,
+  isSuppressionCategory,
   meetsSavingsFloor,
   getHintStatsSummary,
   getHintStatsTotals,
@@ -21542,6 +21763,7 @@ export {
   embeddingsDepsAvailable,
   searchEvidenceSemantically,
   buildDeltaCapsule,
+  PARSER_FINGERPRINT,
   buildLineDiff,
   confirmAndApply,
   findContentDuplicates,
@@ -21563,7 +21785,6 @@ export {
   fenceWithMatches,
   scanAndRecord,
   getTrackedFiles,
-  PARSER_FINGERPRINT,
   stripLeadingAttributes2 as stripLeadingAttributes,
   IMPORT_RE2 as IMPORT_RE,
   yamlOpenQuoteAfter,

package/dist/{token-goat-chunk-OKJX2JWW.mjs → token-goat-chunk-EPX5DWGM.mjs}

@@ -2,7 +2,7 @@ import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
 import {
   detectHarness
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import {
   init_define_import_meta_env
 } from "./token-goat-chunk-A37V4PBF.mjs";

package/dist/{token-goat-chunk-HC5NMGPD.mjs → token-goat-chunk-EQKNR7CN.mjs}

@@ -4,14 +4,14 @@ import {
   buildEvent,
   relay,
   relayInProcess
-} from "./token-goat-chunk-2VVXTAGD.mjs";
+} from "./token-goat-chunk-63XEQMNU.mjs";
 import {
   MAX_STDIN_BYTES,
   readStdinJson
-} from "./token-goat-chunk-A4VBNWSL.mjs";
-import "./token-goat-chunk-3XVGPLDS.mjs";
-import "./token-goat-chunk-OKJX2JWW.mjs";
-import "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-FSC44QOH.mjs";
+import "./token-goat-chunk-CBO45DYZ.mjs";
+import "./token-goat-chunk-EPX5DWGM.mjs";
+import "./token-goat-chunk-3ZR4NLB3.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
 import "./token-goat-chunk-A37V4PBF.mjs";
 export {

package/dist/{token-goat-chunk-A4VBNWSL.mjs → token-goat-chunk-FSC44QOH.mjs}

@@ -9,7 +9,7 @@ import {
   isBlobStale,
   loadBlob,
   storeBlob
-} from "./token-goat-chunk-3XVGPLDS.mjs";
+} from "./token-goat-chunk-CBO45DYZ.mjs";
 import {
   SYMBOL_BODY_CHAR_CAP,
   copilotCliMcpToolsDir,
@@ -24,7 +24,7 @@ import {
   resolveIndexPath,
   shortFingerprint,
   toDisplayPath
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import {
   registerReset
 } from "./token-goat-chunk-EEIDFMEM.mjs";

package/dist/{token-goat-chunk-XSSQFI4C.mjs → token-goat-chunk-GEXHIIKM.mjs}

@@ -7,11 +7,11 @@ import {
   expandGlobs,
   leftoverIntegrations,
   run
-} from "./token-goat-chunk-6FQMEMWX.mjs";
-import "./token-goat-chunk-7A7SBE6R.mjs";
-import "./token-goat-chunk-A4VBNWSL.mjs";
-import "./token-goat-chunk-3XVGPLDS.mjs";
-import "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-6MU6FHE3.mjs";
+import "./token-goat-chunk-US57I7GN.mjs";
+import "./token-goat-chunk-FSC44QOH.mjs";
+import "./token-goat-chunk-CBO45DYZ.mjs";
+import "./token-goat-chunk-3ZR4NLB3.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
 import "./token-goat-chunk-A37V4PBF.mjs";
 export {

package/dist/{token-goat-chunk-3UBORD6Z.mjs → token-goat-chunk-OZAEJQ7L.mjs}

@@ -25,7 +25,7 @@ import {
   runSkeleton,
   runSymbol,
   withPinnedReads
-} from "./token-goat-chunk-7A7SBE6R.mjs";
+} from "./token-goat-chunk-US57I7GN.mjs";
 import {
   buildProjectMap,
   embeddingsDepsAvailable,
@@ -34,7 +34,7 @@ import {
   getProjectIndexCounts,
   isWorkerRunning,
   mapLookupBytesSaved
-} from "./token-goat-chunk-3XVGPLDS.mjs";
+} from "./token-goat-chunk-CBO45DYZ.mjs";
 import {
   ENV_KEYS,
   VERSION,
@@ -48,7 +48,7 @@ import {
   recordStat,
   resolveProjectRoot,
   savedTokensFromBytes
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
 import {
   init_define_import_meta_env

package/dist/{token-goat-chunk-7A7SBE6R.mjs → token-goat-chunk-US57I7GN.mjs}

@@ -68,7 +68,7 @@ import {
   walkProject,
   yamlLineClosesQuote,
   yamlOpenQuoteAfter
-} from "./token-goat-chunk-3XVGPLDS.mjs";
+} from "./token-goat-chunk-CBO45DYZ.mjs";
 import {
   Database,
   PER_FILE_COUNTERFACTUAL_CEILING,
@@ -122,7 +122,7 @@ import {
   unsupportedLanguageName,
   windowsCmdQuoteArg,
   withExtension
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import {
   registerReset
 } from "./token-goat-chunk-EEIDFMEM.mjs";

package/dist/token-goat-hook.mjs

@@ -2,11 +2,11 @@ import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
 import {
   relayInProcess
-} from "./token-goat-chunk-2VVXTAGD.mjs";
-import "./token-goat-chunk-A4VBNWSL.mjs";
-import "./token-goat-chunk-3XVGPLDS.mjs";
-import "./token-goat-chunk-OKJX2JWW.mjs";
-import "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-63XEQMNU.mjs";
+import "./token-goat-chunk-FSC44QOH.mjs";
+import "./token-goat-chunk-CBO45DYZ.mjs";
+import "./token-goat-chunk-EPX5DWGM.mjs";
+import "./token-goat-chunk-3ZR4NLB3.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
 import {
   init_define_import_meta_env

package/dist/token-goat.core.mjs

@@ -2,13 +2,13 @@ import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
 import {
   run
-} from "./token-goat-chunk-6FQMEMWX.mjs";
-import "./token-goat-chunk-7A7SBE6R.mjs";
-import "./token-goat-chunk-A4VBNWSL.mjs";
-import "./token-goat-chunk-3XVGPLDS.mjs";
+} from "./token-goat-chunk-6MU6FHE3.mjs";
+import "./token-goat-chunk-US57I7GN.mjs";
+import "./token-goat-chunk-FSC44QOH.mjs";
+import "./token-goat-chunk-CBO45DYZ.mjs";
 import {
   installEpipeGuard
-} from "./token-goat-chunk-KKHKXUVS.mjs";
+} from "./token-goat-chunk-3ZR4NLB3.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
 import {
   init_define_import_meta_env

package/docs/cli.md

@@ -167,10 +167,10 @@ token-goat pdf-extract manual.pdf --pages 12-15 --layout --head 120
 | `token-goat project exclude <path>` | Add a project root to the blocklist so the worker never indexes it. Writes the resolved absolute path to `[worker] blocked_roots` in `config.toml`; idempotent. It also removes anything already indexed under that path and says how many files went, so excluding a directory means its contents stop being readable through `symbol` rather than merely stopping future indexing. Remove the entry from the config to re-enable indexing, then run `token-goat index` to bring the contents back. |
 | `token-goat project prune [--dry-run]` | Remove blocked/excluded roots that no longer exist on disk. `--dry-run` previews removals without touching the config file. Useful after deleting or moving projects. |
 | `token-goat install` | Wire up hooks (and, with the harness flags below, other AI tool integrations). No `--dry-run` or `--verify` flag — run `token-goat doctor` after install to audit the result. |
-| `token-goat doctor` | Confirm everything is wired correctly. Surfaces install state, cold-import timing, cache hit rates, compaction-budget telemetry, opt-in flag status, and canonical-root sanity. A **Tool names** check reports any tool name a harness sent that reached no handler wanting it, and calls out the ones that differ from a handled name only by capitalisation or punctuation — the signature of a bridge that forgot to rename something, which is otherwise invisible. A **Security** section reports the posture in one place: whether offline mode is on, whether injection scanning is on, whether the Google Drive integration is enabled, whether fetching runs against an allow list or a deny list, whether MCP reads are confined to the project root, and whether the data directory is readable by other local users. It only warns when a protection that ships on has been switched off, so a default install stays quiet. It read-only audits `~/.copilot/mcp-config.json` for globally configured Chrome DevTools or Playwright `npx` launchers, recommending project scope or removal when inactive; it never prints server configuration or secrets. On Windows, it also reports duplicate Chrome DevTools/Playwright MCP launchers and orphaned Node processes without terminating anything. Pass `--context` to show the **Context footprint** section: a fill bar with severity (ok / warn / high / URGENT), per-component breakdown (skills catalog, loaded skill bodies, CLAUDE.md+MEMORY.md, conversation estimate), session-to-session growth trend with sessions-to-URGENT projection, and tiered compaction recommendations (Tier 0–4) naming the exact commands to run. Auto-shown when fill > 40 % or any loaded skill > 2 K tokens lacks a compact. `--json` emits the check results (one entry per check, with `ok`/`warn`/`fail` status) as JSON instead of text. |
+| `token-goat doctor` | Confirm everything is wired correctly. Surfaces install state, cold-import timing, cache hit rates, compaction-budget telemetry, opt-in flag status, and canonical-root sanity. A **Parser freshness** check reports how much of the index for this project was written by a different build of the extractor. The stamp only refreshes when something touches a file, so after an upgrade a project goes on answering `symbol`, `read`, `outline` and `skeleton` from the previous extractor with nothing saying so. It warns past a quarter and names the fix: a plain `token-goat index` in that project, which is enough on its own, since a parser mismatch reparses without `--force`. A **Tool names** check reports any tool name a harness sent that reached no handler wanting it, and calls out the ones that differ from a handled name only by capitalisation or punctuation — the signature of a bridge that forgot to rename something, which is otherwise invisible. A **Security** section reports the posture in one place: whether offline mode is on, whether injection scanning is on, whether the Google Drive integration is enabled, whether fetching runs against an allow list or a deny list, whether MCP reads are confined to the project root, and whether the data directory is readable by other local users. It only warns when a protection that ships on has been switched off, so a default install stays quiet. It read-only audits `~/.copilot/mcp-config.json` for globally configured Chrome DevTools or Playwright `npx` launchers, recommending project scope or removal when inactive; it never prints server configuration or secrets. On Windows, it also reports duplicate Chrome DevTools/Playwright MCP launchers and orphaned Node processes without terminating anything. Pass `--context` to show the **Context footprint** section: a fill bar with severity (ok / warn / high / URGENT), per-component breakdown (skills catalog, loaded skill bodies, CLAUDE.md+MEMORY.md, conversation estimate), session-to-session growth trend with sessions-to-URGENT projection, and tiered compaction recommendations (Tier 0–4) naming the exact commands to run. Auto-shown when fill > 40 % or any loaded skill > 2 K tokens lacks a compact. `--json` emits the check results (one entry per check, with `ok`/`warn`/`fail` status) as JSON instead of text. |
 | `token-goat capabilities` | List every capability that can send data off this machine or leave data on it, with whether it is currently on, the config key that decides that, and the exact `file::symbol` where the decision is made — so a reviewer can open the code rather than take the list's word for it. `--json` emits the same thing for a pipeline to assert on, which is the point: the answer comes from the binary installed on your machine, not from documentation that may describe a different build. A test in the suite fails the build when a module that can open a network connection is missing from this list, and equally when the list names one that no longer connects anywhere. |
 | `token-goat baseline` | Emit a project map: file count, per-language file counts, the top indexed symbols (by name/kind/location), and the most recently modified files. `--subagent` emits a terser variant (fewer symbols, fewer recent files) for context handed to a freshly spawned subagent; `--json` for the machine-readable form. |
-| `token-goat compact-doc <path>` | Build an extractive compact sidecar for a large reference doc (`.md`/`.markdown`). The compact is stored in the token-goat data dir as a SHA-keyed sidecar; `pre_read` serves it in place of the full file when it exists and is fresh, saving 80–95% of context tokens. Use `--force` to rebuild, `--sentences N` to control lines per section (default 2), `--show` to print the result. The sidecar is automatically marked stale when you edit the source file. Config: `[hints] stable_doc_compacts = true` (default on). |
+| `token-goat compact-doc <path>` | Build an extractive compact sidecar for a large reference doc (`.md`/`.markdown`). The compact is stored in the token-goat data dir as a SHA-keyed sidecar; `pre_read` serves it in place of the full file when it exists and is fresh, typically saving 60–95% of the tokens the full read would cost (measured across this repo's own 44 docs: median 67%, range 5–99%, depending on how much of the doc is prose under headings). Use `--force` to rebuild, `--sentences N` to control lines per section (default 2), `--show` to print the result. The sidecar is automatically marked stale when you edit the source file. Config: `[hints] stable_doc_compacts = true` (default on). |
 
 Missed lookups recover surgically: `read` and `section` print a "Did you mean…?" list on a miss, and `section` auto-redirects on an unambiguous heading-prefix match — a typo costs at most one extra glance, not a re-read.
 
@@ -302,12 +302,12 @@ that category — the real cost of emitting it, not just how often it fired):
 
 ```
 $ token-goat hint-stats
-category              emitted  acted-on  efficacy  suppressed  manual+  manual-  spent
-bash_redirect          42       9         21.4%     no          0        0        3150
-bash_recall            18       15        83.3%     no          0        0        1080
-read_reread_dedup      11       2         18.2%     no          0        0        660
-read_structural_nav    7        1         14.3%     yes         0        1        420
-edit_reread_suggest    3        0         0%        no          0        0        180
+category              emitted  acted-on  efficacy   suppressed  manual+  manual-  spent
+bash_redirect          42       9         21.4%      no          0        0        3150
+bash_recall            18       15        83.3%      no          0        0        1080
+read_reread_dedup      11       2         18.2% *    no          0        0        660
+read_structural_nav    7        1         14.3%      yes         0        1        420
+edit_reread_suggest    3        0         0% *       no          0        0        180
 
 TOTAL   saved=48200   spent=5490   net=42710
 ```
@@ -325,6 +325,13 @@ emissions (default 5) AND its efficacy falls below `hint_stats.suppress_threshol
 emission. Once suppressed, that hook stops emitting that category until `token-goat hint-stats
 --reset` clears the tracked data. Configure both knobs with `token-goat config set hint_stats.min_sample_size <n>` / `token-goat config set hint_stats.suppress_threshold_pct <pct>`.
 
+A `*` on an efficacy figure means that category is scored on an absence. Those hints ask the
+agent *not* to do something, so a window that expires with no re-read counts as compliance, while
+an unmarked category only scores when the agent actually runs the command the hint named. The two
+percentages sit on different scales and comparing them straight across gives the wrong answer: a
+high starred figure means the warned-against read was not seen, not that the hint persuaded
+anyone.
+
 "Acted on" is a real, session-scoped signal (the exact file path or cached-output id the hint's
 own text pointed at is checked against the next few tool calls in that session) — not a guess —
 but it is a proxy for correlation, not proof of causation: a match means the agent ran the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-goat",
-  "version": "2.9.3",
+  "version": "2.9.4",
   "description": "Surgical token-reduction companion for Claude Code and other AI coding agents",
   "type": "module",
   "main": "./dist/token-goat.mjs",