@hone-ai/cli 1.38.1 → 1.39.0

package/lib/bundle-paths.js

@@ -325,6 +325,17 @@ function anchorLineForStory(content, storyText) {
  *
  * The fallback is the OLD behaviour on purpose: a term that is only ever mentioned still
  * gets the operator a window near it, which beats none.
+ *
+ * HC-GF-203-followup-1: a MENTION is the term standing whole, not the term's letters inside a
+ * longer identifier. The fallback was a bare `indexOf`, so `info` landed in `information`,
+ * `auth` in `authorize` and `Promise.all` in `Promise.allSettled` — and each such offset became
+ * a site in `anchorSitesForStory`, spending one of its 6 slots and a window on text that does
+ * not contain the term. Measured 2026-10-07 at the production cap over every roadmap row
+ * against cli/hone-cli.js and server/src/services/orchestrator.js: 187 of 6,210 sites, in 161
+ * of 1,224 windowed excerpts, 106 of them at the 6-site limit, where the wasted slot cost
+ * another term its window. A term that never stands whole is now -1, exactly like a term
+ * the file lacks: HC-GF-188's rule, "could not anchor" stays distinguishable from "anchored
+ * here", applies to a window around `information` as much as to one around line 1.
  */
 /**
  * HC-GF-206-followup-1: a collapsed hit is a real site — the collapse only means it EXPECTS to
@@ -355,6 +366,11 @@ function anchorSitesForStory(content, storyText, max = 6) {
     if (def === -1) continue;
     const t = anchor.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const offsets = [def];
+    // The STRICT form on purpose, unlike `wholeTerm`. HC-GF-206-followup-5 measured `wholeTerm` here:
+    // a term with a punctuation edge (`/prompts/`, `.json`) then takes every occurrence as a site and
+    // crowds the rest out of the 6 — 74 of 1,218 excerpts changed, 9 terms gained a window, 28 lost one.
+    // With the strict form such a term gets its first whole occurrence (`def`), and the marker names
+    // it when no window shows it.
     for (const m of text.matchAll(new RegExp(`(?<![\\w$])${t}(?![\\w$])`, 'g'))) offsets.push(m.index);
     for (const off of offsets) {
       const line = text.slice(0, off).split('\n').length;
@@ -370,8 +386,29 @@ function anchorSitesForStory(content, storyText, max = 6) {
   return { sites, collapsed };
 }
 
+/**
+ * A term standing WHOLE — HC-GF-203-followup-1: no identifier character touches an edge of the term
+ * that is itself an identifier character. `checkBudget(` stands whole in `checkBudget(orgId)` — its
+ * own `(` is the boundary on that side — and `info` does not in `information`.
+ *
+ * HC-GF-206-followup-5: one copy, read by `definitionIndexOf` and `unanchoredTerms`. With the strict
+ * `(?<![\w$])…(?![\w$])` in `unanchoredTerms`, the two disagreed on every term with a punctuation
+ * edge: `definitionIndexOf` found `checkBudget(` and the marker said nothing, because the strict
+ * form calls it absent. `anchorSitesForStory`'s scan for further hits deliberately keeps the strict
+ * form; see there.
+ *
+ * @returns {{t: string, before: string, after: string}} the escaped term and the two lookarounds
+ */
+function wholeTerm(term) {
+  return {
+    t: term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+    before: /^[\w$]/.test(term) ? '(?<![\\w$])' : '',
+    after: /[\w$]$/.test(term) ? '(?![\\w$])' : '',
+  };
+}
+
 function definitionIndexOf(text, term) {
-  const t = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const { t, before, after } = wholeTerm(term);
   // Ordered by how strongly each shape asserts "this is where it lives".
   const DEFINITION_FORMS = [
     `\\.command\\(\\s*['"\`]${t}\\b`,           // CLI command registration
@@ -379,13 +416,16 @@ function definitionIndexOf(text, term) {
     `class\\s+${t}\\b`,                           // class declaration
     `(?:const|let|var)\\s+${t}\\s*=`,             // binding
     `exports\\.${t}\\s*=`,                        // named export
-    `${t}\\s*[:=]\\s*(?:async\\s*)?(?:function|\\()`, // property holding a function
+    // The one form with nothing in front of the term: without `before`, `name` is "defined"
+    // by `basename = (` and `run` by `rerun: function`.
+    `${before}${t}\\s*[:=]\\s*(?:async\\s*)?(?:function|\\()`, // property holding a function
   ];
   for (const form of DEFINITION_FORMS) {
     const m = new RegExp(form).exec(text);
     if (m) return m.index;
   }
-  return text.indexOf(term);
+  const mention = new RegExp(`${before}${t}${after}`).exec(text);
+  return mention ? mention.index : -1;
 }
 
 /**
@@ -402,9 +442,17 @@ function definitionIndexOf(text, term) {
  * Judged against the FINAL windows, not the site list, so it holds whatever dropped the term — the
  * site limit, the budget, a collapse — and needs no knowledge of how the layout was chosen.
  *
- * A term counts as occurring only where it stands as a whole word. `definitionIndexOf` falls back to
- * a bare `indexOf`, which finds `info` inside `information`; reporting that as "`info` is at line N"
- * would send an agent to a line that does not contain it.
+ * A term counts as occurring only where it stands whole (`wholeTerm`); reporting `info` inside
+ * `information` as "`info` is at line N" would send an agent to a line that does not contain it.
+ * `definitionIndexOf` applies the same rule since HC-GF-203-followup-1 (its fallback was a bare
+ * `indexOf`); the check here stays, because this is what names a term to the agent.
+ *
+ * HC-GF-206-followup-5: this read the strict form, which calls every term with a punctuation edge
+ * absent unless that edge happens to sit next to a non-identifier character. Measured 2026-10-07 at
+ * the production cap over every roadmap row against cli/hone-cli.js and orchestrator.js: 44 such
+ * terms in 40 of 1,218 windowed excerpts were in the file, in no window, and not named; and 42
+ * were named as outside every window while a window showed them (`.md` in `README.md`). After: 0 and
+ * 0, with every window byte-identical and no term pushed out of the marker or the notice.
  *
  * @param {string} content full file contents
  * @param {string} storyText
@@ -428,11 +476,10 @@ function unanchoredTerms(content, storyText, ranges) {
   for (const term of new Set(storyTermsOf(storyText))) {
     const def = definitionIndexOf(text, term);
     if (def === -1) continue;
-    const t = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const mentions = [...text.matchAll(new RegExp(`(?<![\\w$])${t}(?![\\w$])`, 'g'))].map((m) => lineOf(m.index));
+    const { t, before, after } = wholeTerm(term);
+    const mentions = [...text.matchAll(new RegExp(`${before}${t}${after}`, 'g'))].map((m) => lineOf(m.index));
     if (!mentions.length) continue;
-    // Covered only by a whole-word occurrence. The bundler may have anchored on `def` itself, but
-    // when `def` is the indexOf fallback that window shows `information`, not `info`.
+    // Covered only by a whole occurrence.
     if (mentions.some(covered)) continue;
     const defLine = lineOf(def);
     out.push({ term, line: mentions.includes(defLine) ? defLine : mentions[0] });

package/lib/call-sites.js

@@ -0,0 +1,489 @@
+'use strict';
+/**
+ * call-sites.js — HC-GF-217: the CLI searches the checkout for the symbols a story names, so the server never has to.
+ *
+ * WHY. The shared-chokepoint guardrail asks the planner to enumerate every call site of a function it changes
+ * "from an actual search". A server-executed agent is one text completion with no shell and no filesystem
+ * (`cwd: os.tmpdir()` in claude-cli-provider.js — deliberate, the server has no tools and cannot execute), so
+ * the guardrail demanded something no agent on that path can do, and the step paused on a condition nobody
+ * could meet. The agent was right to refuse: on HC-GF-293 `git grep -w ensureConnected` finds an external caller
+ * (server/src/services/ip-retrieval-audit.js) that was in nobody's bundle. Only this CLI, which holds the
+ * checkout, can search. It searches, sends the result in the run config (`config.call_sites`), and the server only
+ * renders it (server/src/services/call-sites.js).
+ *
+ * THE RULES THIS FILE KEEPS
+ *  - A list is COMPLETE only when it is the whole answer. A symbol with more hits than MAX_HITS_PER_SYMBOL is
+ *    'incomplete' and carries its true total; a truncated list is never presented as the whole.
+ *  - A search that did not run is 'not_searched', never zero callers. `git grep` exits 1 for "no match" and 128
+ *    for a fatal error; only the first is an answer. A timeout, a missing git and an output overflow are
+ *    classified failures, not empty results.
+ *  - A line from a hidden or credential-looking path is never sent (cli/lib/context-reserve.js contentRefusal,
+ *    the rule a re-serve uses); it is counted, so the planner knows callers exist that it cannot see. The check
+ *    is made on the disk as it is now: `git grep` follows a DIRECTORY that was replaced by a symlink after the
+ *    commit (measured with git 2.50.1: a tracked `d/secret.txt` read from outside the checkout), so a path that
+ *    does not resolve to itself inside the checkout is withheld (HC-GF-351's repoRealPath).
+ *  - `git grep` prints `error: ...` for a file it cannot read and still exits 0 or 1 on the strength of the OTHER
+ *    files, so a missing caller would read as COMPLETE (or "COMPLETE: 0 hits"). ANY output on stderr makes the
+ *    symbol 'not_searched': git's exit code alone is not the answer. (Any, not just `error:` lines: a message we
+ *    did not anticipate is exactly the one we cannot judge, and a clean grep prints nothing.)
+ *  - A name that looks like a secret (`AWS_SECRET_ACCESS_KEY`, `STRIPE_API_KEY`) is never searched: the story text
+ *    chooses what is grepped, and the hit LINE (`STRIPE_SECRET_KEY=sk_live_…`) would be sent to the server.
+ *  - git is run with an argv array (execFile), never a shell string. The symbols are also restricted to
+ *    `[A-Za-z0-9_]` identifiers, so even a hostile story cannot reach the command line.
+ *
+ * SCOPE: every file git tracks in the repository, searched from its TOP LEVEL (`git rev-parse --show-toplevel`)
+ * wherever `hone` ran — `git grep` from a subdirectory searches only that subtree and would still say COMPLETE — as
+ * it is on disk, EXCEPT documentation files (PROSE_EXTENSIONS), which are counted and not listed. Not searched at
+ * all: submodules (--no-recurse-submodules), the contents of tracked symbolic links (git grep does not follow
+ * them), tracked files deleted from the working tree, and files git treats as binary (those are COUNTED: a
+ * second `git grep -l` without -I names how many files match only as binary, and such a symbol is never
+ * COMPLETE). Not
+ * `codebase.source_dirs` + test dirs: that setting is the scope of the rendered TREE, and it drifts —
+ * `hone setup` once wrote `src/` for every Node repository (HC-DF-002) — so a search scoped by it would call a
+ * list complete that missed every caller outside it. Documentation is excluded because a roadmap row or a
+ * runbook that mentions a function is not a call site, and counting it would mark the symbols a story is about
+ * (the row that describes the change always names them) as incomplete on every story. Tests ARE searched: they
+ * are consumers the plan must update. Untracked and ignored files are not, by construction.
+ *
+ * LANGUAGE-AGNOSTIC. A symbol is a backticked span that is one identifier (optionally qualified and/or called)
+ * which is EITHER compound — camelCase, PascalCase, snake_case or SCREAMING_SNAKE — OR a single word the story
+ * writes as a call or qualified (`charge()`, `Billing.charge`, `billing::charge`, `obj->charge`; at least 3
+ * characters). A bare plain word (`wait`, `end`, `connect`) names too many things to be worth a list, and the cap
+ * would be spent on it; writing it as a call is how an operator says "this one" (a shared chokepoint is often a
+ * short name). Explicitly written spans are searched first. Nothing here knows a language or a Hone name. Known
+ * limits: ASCII identifiers only; case-sensitive, so a case-insensitive language's other spellings are not found;
+ * a symbol the story does not put in backticks is not searched.
+ *
+ * WIDELY USED FUNCTIONS. A real shared chokepoint has many consumers, so its hit list outgrows MAX_HITS_PER_SYMBOL.
+ * Past the cap the entry ALSO carries a per-file list (path + hit count) for every file with a hit; the server calls
+ * a symbol whose file list accounts for every file and hit COMPLETE AT FILE LEVEL, which the planner accepts as the
+ * enumeration. The lists of all symbols together are held to MAX_FILE_LIST_BYTES, and a cut list says so.
+ *
+ * I/O (git, the disk) is injected so the unit tests drive every branch without a repository.
+ */
+
+const { execFile } = require('node:child_process');
+const path = require('node:path');
+const { gitEnv } = require('./git-env');
+const { contentRefusal, repoRealPath } = require('./context-reserve');
+
+const CALL_SITES_VERSION = 1;
+/** The only scope id today; the server writes its own description of it. */
+const SCOPE = 'tracked-repo';
+
+// The caps. server/src/services/call-sites.js accepts at least these (pinned by a cross-package test): a server
+// that took less would quietly turn a complete list into an incomplete one.
+const MAX_SYMBOLS = 6;
+/** Secret-looking names are reported, not searched; they take no slot of the 6 but are reported up to this many. */
+const MAX_REFUSED = 2;
+/** Past MAX_HITS_PER_SYMBOL a symbol also carries a per-file list (path + hit count), up to this many files... */
+const MAX_FILE_LIST_FILES = 300;
+/** ...and all the symbols' file lists together stay under this many bytes of JSON (server/src/lib/batch-body-limit.js budgets it). */
+const MAX_FILE_LIST_BYTES = 96 * 1024;
+const MAX_OMITTED_NAMES = 20;
+const MAX_HITS_PER_SYMBOL = 40;
+const MAX_LINE_CHARS = 160;
+const MAX_PATH_CHARS = 260;
+/** The longest identifier it will search; the server reads no longer one (a longer name would be dropped there). */
+const MAX_SYMBOL_CHARS = 100;
+
+const SEARCH_TIMEOUT_MS = 20_000;
+/** All the symbols of one story together: a repository too big to search in this long is told so, not waited on. */
+const TOTAL_BUDGET_MS = 45_000;
+const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+
+/** Documentation, not code. Deliberately not `.txt`: CMakeLists.txt and requirements.txt hold real references. */
+const PROSE_EXTENSIONS = Object.freeze(['md', 'mdx', 'markdown', 'rst', 'adoc', 'asciidoc']);
+
+// ── Choosing the symbols ────────────────────────────────────────────────────────────────────────
+
+const BACKTICKED = /`([^`\n]{2,200})`/g;
+// One identifier, optionally qualified (`a.b`, `A::b`, `a->b`, `A#b`) and optionally called (`f()`, `f(x)`). The LAST
+// segment is the symbol: `this.ensureConnected` is a reference to `ensureConnected` wherever it is called from.
+// Group 1 is the qualifier (empty when there is none), 2 the name, 3 the call's parentheses (undefined when not called).
+const NAME_SPAN = /^((?:[A-Za-z_][A-Za-z0-9_]*(?:\.|::|->|#))*)([A-Za-z_][A-Za-z0-9_]*)\s*(\([^`]*\))?$/;
+/** A name that looks like a secret is never searched (its hit lines are the values). */
+const SECRET_NAME = /secret|passw|token|api_?key|credential|private_?key|access_?key/i;
+const SECRET_REASON = 'the name looks like a secret or credential, and the lines that mention one hold its value, so it is never searched';
+/** `config.yaml`, `index.js`: a qualified span whose last segment is a file extension names a file, not a symbol. */
+const FILE_EXTENSIONS = new Set(['js', 'jsx', 'mjs', 'cjs', 'ts', 'tsx', 'json', 'yaml', 'yml', 'toml', 'xml', 'html', 'htm', 'css', 'scss',
+  'md', 'mdx', 'txt', 'lock', 'py', 'pyi', 'rb', 'go', 'rs', 'java', 'kt', 'swift', 'cs', 'php', 'sh', 'bash', 'zsh', 'sql', 'cpp', 'hpp',
+  'cfg', 'conf', 'ini', 'env', 'log', 'csv', 'svg', 'png', 'jpg', 'jpeg', 'gif', 'pdf', 'zip', 'tar', 'gz']);
+
+/**
+ * Is this identifier compound (worth a search), as opposed to a plain word? An identifier with an inner
+ * underscore (`wait_for_ready`, `MAX_RETRIES`) or an inner lower-to-upper hump (`ensureConnected`, `UserService`,
+ * `HTTPServer`). A single capitalised word (`Property`) cannot be told from English and is not compound. Leading
+ * and trailing underscores do not count: `__init__` is a plain word in a protocol's clothes.
+ * @param {string} name
+ */
+function isCompoundIdentifier(name) {
+  if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) return false;
+  const core = name.replace(/^_+|_+$/g, '');
+  if (core.length < 4) return false;
+  if (/[A-Za-z0-9]_+[A-Za-z0-9]/.test(core)) return true;
+  if (/[a-z0-9][A-Z]/.test(core)) return true;
+  return /[A-Z]{2,}[a-z]/.test(core);
+}
+
+/**
+ * What a backticked span says it is about.
+ *  - a COMPOUND name is a symbol however it is written;
+ *  - a single word (`charge`, `authorize`, `dispatch`) is a symbol only when the story WRITES it as one: called
+ *    (`charge()`), or qualified (`Billing.charge`, `billing::charge`, `obj->charge`). That is how an operator says
+ *    "this plain word is the function I mean" — the one lever for a shared chokepoint with a short name. At least
+ *    3 characters, not a dunder, not the extension of a file name (`config.yaml`).
+ * `explicit` is true for the called/qualified form of either kind; those are ranked first.
+ * @returns {{name: string, explicit: boolean}|null}
+ */
+function symbolOfSpan(span) {
+  const m = NAME_SPAN.exec(span.trim());
+  if (!m) return null;
+  const [, qualifier, name, call] = m;
+  if (name.length > MAX_SYMBOL_CHARS) return null;
+  const explicit = qualifier !== '' || call !== undefined;
+  if (isCompoundIdentifier(name)) return { name, explicit };
+  if (!explicit || name.length < 3 || /^__.*__$/.test(name)) return null;
+  if (call === undefined && qualifier.endsWith('.') && FILE_EXTENSIONS.has(name.toLowerCase())) return null;
+  return { name, explicit };
+}
+
+/**
+ * The symbols a story puts in backticks: explicitly written ones (called or qualified) first, then the rest, each
+ * group the ones the story talks about most first (then in the order it first names them), at most `max` of them.
+ * Names that look like a secret are returned in `refused`, not searched and not counted against `max`. The rest are
+ * returned by name so the block can say what was not searched.
+ * @param {string} storyText
+ * @param {{max?: number}} [opts]
+ * @returns {{symbols: string[], omitted: string[], omittedTotal: number, refused: string[]}}
+ */
+function pickSymbols(storyText, { max = MAX_SYMBOLS } = {}) {
+  const counts = new Map();
+  const explicitNames = new Set();
+  for (const m of String(storyText || '').matchAll(BACKTICKED)) {
+    const sym = symbolOfSpan(m[1]);
+    if (!sym) continue;
+    counts.set(sym.name, (counts.get(sym.name) || 0) + 1);
+    if (sym.explicit) explicitNames.add(sym.name);
+  }
+  // Array.prototype.sort is stable (ES2019), and a Map iterates in insertion order: ties keep the order the story first names them.
+  const all = [...counts.keys()].sort((a, b) => (explicitNames.has(b) - explicitNames.has(a)) || (counts.get(b) - counts.get(a)));
+  const refusedAll = all.filter((n) => SECRET_NAME.test(n));
+  const ranked = all.filter((n) => !SECRET_NAME.test(n));
+  const refused = refusedAll.slice(0, MAX_REFUSED);
+  const beyond = [...ranked.slice(max), ...refusedAll.slice(MAX_REFUSED)];
+  return {
+    symbols: ranked.slice(0, max),
+    omitted: beyond.slice(0, MAX_OMITTED_NAMES),
+    omittedTotal: beyond.length,
+    refused,
+  };
+}
+
+// ── Running git ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Run `git <argv>` in `cwd`. execFile with an argv array: no shell ever sees an element of it. (`bin` is for tests.)
+ * @returns {Promise<{status: number|null, stdout: string, stderr: string, failure: string|null}>}
+ *   `failure` is a stable classification of why there is no answer (never git's stderr, which can carry paths);
+ *   `status` is git's exit code when it ran to the end; `stderr` is what git printed there, for the caller to JUDGE
+ *   and never to repeat (a `git grep` that could not read a file says so there and still exits 0 or 1).
+ */
+function runGit(argv, { cwd, timeoutMs = SEARCH_TIMEOUT_MS, maxBuffer = MAX_OUTPUT_BYTES, bin = 'git' } = {}) {
+  return new Promise((resolve) => {
+    execFile(bin, argv, { cwd, env: gitEnv(), encoding: 'utf8', timeout: timeoutMs, maxBuffer, windowsHide: true }, (err, stdout, stderr) => {
+      const out = stdout || '';
+      const errText = stderr || '';
+      if (!err) return resolve({ status: 0, stdout: out, stderr: errText, failure: null });
+      if (err.code === 'ENOENT') return resolve({ status: null, stdout: '', stderr: '', failure: 'git is not installed or not on PATH' });
+      if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+        return resolve({ status: null, stdout: '', stderr: '', failure: `the search printed more than ${maxBuffer / (1024 * 1024)} MiB, too many hits to list` });
+      }
+      if (err.killed || err.signal) return resolve({ status: null, stdout: '', stderr: '', failure: `git grep timed out after ${timeoutMs / 1000}s` });
+      if (typeof err.code === 'number') return resolve({ status: err.code, stdout: out, stderr: errText, failure: null });
+      return resolve({ status: null, stdout: '', stderr: '', failure: 'git grep could not be run' });
+    });
+  });
+}
+
+/**
+ * `git grep -n -z` output: `path NUL line NUL text LF` per hit, read in order because a path may hold a newline.
+ * @returns {Array<{path: string, line: number, text: string}>|null}  null when the output is not that shape
+ */
+function parseGrepOutput(out) {
+  const hits = [];
+  let at = 0;
+  while (at < out.length) {
+    const p = out.indexOf('\0', at);
+    const l = p < 0 ? -1 : out.indexOf('\0', p + 1);
+    if (l < 0) return null;
+    const lineNo = Number(out.slice(p + 1, l));
+    if (!Number.isInteger(lineNo) || lineNo < 1) return null;
+    let end = out.indexOf('\n', l + 1);
+    if (end < 0) end = out.length;
+    hits.push({ path: out.slice(at, p), line: lineNo, text: out.slice(l + 1, end).replace(/\r$/, '') });
+    at = end + 1;
+  }
+  return hits;
+}
+
+// ── Judging what may be sent ────────────────────────────────────────────────────────────────────
+
+/**
+ * What one hit's path is: documentation (counted), withheld (counted, never sent) or sendable.
+ * @param {string} rel
+ * @param {(rel: string) => string|null} realPath  where `rel` resolves on the disk now, relative to the checkout
+ * @returns {'prose'|'withheld'|'ok'}
+ */
+function classifyPath(rel, realPath) {
+  const ext = path.posix.extname(rel).slice(1).toLowerCase();
+  if (PROSE_EXTENSIONS.includes(ext)) return 'prose';
+  if (rel.length > MAX_PATH_CHARS || /[\x00-\x1f\x7f]/.test(rel)) return 'withheld';
+  if (contentRefusal(rel)) return 'withheld';
+  // A directory above the file may have been replaced by a link since the commit; git reads through it.
+  let real = null;
+  try { real = realPath(rel); } catch { real = null; }
+  return real === rel ? 'ok' : 'withheld';
+}
+
+/** A hit's text on one line of at most MAX_LINE_CHARS, windowed on the symbol when the line is longer. */
+function lineText(text, symbol) {
+  const t = String(text).replace(/[\x00-\x1f\x7f]/g, ' ').trim();
+  if (t.length <= MAX_LINE_CHARS) return t;
+  const at = t.search(new RegExp(`(?<![A-Za-z0-9_])${symbol}(?![A-Za-z0-9_])`));
+  const start = at < 0 ? 0 : Math.max(0, at - Math.floor(MAX_LINE_CHARS / 3));
+  const lead = start > 0 ? '…' : '';
+  const room = MAX_LINE_CHARS - lead.length - 1;
+  const trail = start + room < t.length ? '…' : '';
+  return lead + t.slice(start, start + room) + trail;
+}
+
+const STDERR_REASON = 'git grep reported errors (it could not read some files), so the list may be missing callers';
+
+/**
+ * Why a `git grep` run is not an answer, or null when it is one. Exit 0 (hits) and 1 (none) are answers ONLY with
+ * an empty stderr: git prints `error: ...` for a file it cannot read (permission, EIO) and still exits on the
+ * strength of the other files.
+ */
+function grepProblem(r) {
+  if (r.failure) return r.failure;
+  if (r.status !== 0 && r.status !== 1) return `git grep failed (exit ${r.status})`;
+  if (typeof r.stderr === 'string' && r.stderr.trim() !== '') return STDERR_REASON;
+  return null;
+}
+
+/** `git grep -l -z` output: the NUL-terminated names of the files that match. null when it is not that shape. */
+function parseFileList(out) {
+  if (out === '') return [];
+  if (!out.endsWith('\0')) return null;
+  return out.slice(0, -1).split('\0');
+}
+
+/**
+ * One symbol's entry for `config.call_sites.symbols`.
+ *  - 'complete': `hits` is every hit in scope that may be sent; `withheld` more sit in paths that never are.
+ *  - 'incomplete': more hits than MAX_HITS_PER_SYMBOL, or files that match only as binary; `hits` is the first of
+ *    them and `total` the true count. When it is the hit cap, `file_list` names every file with a hit and its count
+ *    (`file_list_complete` says whether that list is itself whole) — the server then calls it COMPLETE AT FILE LEVEL.
+ *  - 'not_searched': no answer, and `reason` says why. Never to be read as "no callers".
+ * `binary` is how many files match only when git's binary-file skip (-I) is off; they cannot be listed.
+ */
+async function searchSymbol(symbol, { run, realPath }) {
+  // Defence in depth: pickSymbols only yields identifiers, but this is exported, and the symbol reaches an argv and a RegExp.
+  if (typeof symbol !== 'string' || !/^[A-Za-z0-9_]+$/.test(symbol)) {
+    return { symbol: String(symbol).slice(0, 80), status: 'not_searched', reason: 'not an identifier' };
+  }
+  if (SECRET_NAME.test(symbol)) return { symbol, status: 'not_searched', reason: SECRET_REASON };
+  const r = await run(['grep', '-n', '-w', '-F', '-I', '-z', '--no-color', '--no-recurse-submodules', '-e', symbol]);
+  const problem = grepProblem(r);
+  if (problem) return { symbol, status: 'not_searched', reason: problem };
+  // 1 is git grep's "no line selected": no text hit. Binary files are checked below either way.
+  const parsed = r.status === 1 ? [] : parseGrepOutput(r.stdout);
+  if (parsed === null) return { symbol, status: 'not_searched', reason: 'git grep printed output that could not be read' };
+
+  // -I skipped every file git treats as binary (.gitattributes `-diff`/`binary`, a generated stub, a NUL byte).
+  // The same search with -l and without -I names them: the ones that appear only there are matches we cannot list.
+  const b = await run(['grep', '-l', '-z', '-w', '-F', '--no-color', '--no-recurse-submodules', '-e', symbol]);
+  const bProblem = grepProblem(b);
+  if (bProblem) return { symbol, status: 'not_searched', reason: `the binary-file check failed: ${bProblem}` };
+  const matching = b.status === 1 ? [] : parseFileList(b.stdout);
+  if (matching === null) return { symbol, status: 'not_searched', reason: 'the binary-file check printed output that could not be read' };
+  const textFiles = new Set(parsed.map((h) => h.path));
+  const binary = matching.filter((f) => !textFiles.has(f)).length;
+
+  let prose = 0;
+  let withheld = 0;
+  const sendable = [];
+  const kinds = new Map();
+  for (const hit of parsed) {
+    let kind = kinds.get(hit.path);
+    if (!kind) { kind = classifyPath(hit.path, realPath); kinds.set(hit.path, kind); }
+    if (kind === 'prose') prose += 1;
+    else if (kind === 'withheld') withheld += 1;
+    else sendable.push(hit);
+  }
+  const total = sendable.length + withheld;
+  const hits = sendable.slice(0, MAX_HITS_PER_SYMBOL).map((h) => ({ path: h.path, line: h.line, text: lineText(h.text, symbol) }));
+  const perFile = new Map();
+  for (const h of sendable) perFile.set(h.path, (perFile.get(h.path) || 0) + 1);
+  const entry = {
+    symbol,
+    status: hits.length + withheld === total && binary === 0 ? 'complete' : 'incomplete',
+    total,
+    files: perFile.size,
+    withheld,
+    prose,
+    binary,
+    hits,
+  };
+  if (sendable.length > MAX_HITS_PER_SYMBOL) {
+    const all = [...perFile].map(([p, n]) => ({ path: p, hits: n }));
+    entry.file_list = all.slice(0, MAX_FILE_LIST_FILES);
+    entry.file_list_complete = all.length <= MAX_FILE_LIST_FILES;
+  }
+  return entry;
+}
+
+/** Keep the symbols' file lists inside MAX_FILE_LIST_BYTES together; a list that is cut says so. */
+function fitFileLists(symbols) {
+  let room = MAX_FILE_LIST_BYTES;
+  for (const s of symbols) {
+    if (!s.file_list) continue;
+    const kept = [];
+    for (const f of s.file_list) {
+      const size = Buffer.byteLength(JSON.stringify(f), 'utf8') + 1;
+      if (size > room) { s.file_list_complete = false; break; }
+      room -= size;
+      kept.push(f);
+    }
+    if (kept.length === 0) { delete s.file_list; s.file_list_complete = false; } else s.file_list = kept;
+  }
+}
+
+async function headCommit(run) {
+  const r = await run(['rev-parse', 'HEAD']);
+  const sha = r.failure || r.status !== 0 ? '' : r.stdout.trim();
+  return /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+}
+
+// ── The CLI's one entry point ───────────────────────────────────────────────────────────────────
+
+const info = (text) => ({ level: 'info', text });
+const warn = (text) => ({ level: 'warn', text });
+
+/**
+ * Search the checkout for every compound symbol the story names.
+ * @param {{cwd: string, storyText: string, run?: Function, realPath?: Function, now?: () => number, maxSymbols?: number}} o
+ * @returns {Promise<{callSites: object|null, notes: Array<{level: string, text: string}>}>}
+ *   `callSites` is null when the story names no compound symbol: no field is sent and nothing changes.
+ */
+async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now, maxSymbols = MAX_SYMBOLS }) {
+  const notes = [];
+  const picked = pickSymbols(storyText, { max: maxSymbols });
+  if (picked.symbols.length === 0 && picked.refused.length === 0) return { callSites: null, notes };
+
+  // From the repository's top level, wherever `hone` ran: `git grep` from a subdirectory searches only that subtree.
+  let root = cwd;
+  if (!run) {
+    const top = await runGit(['rev-parse', '--show-toplevel'], { cwd });
+    const dir = top.failure || top.status !== 0 ? '' : top.stdout.trim();
+    if (dir) root = dir;
+  }
+  const git = run || ((argv) => runGit(argv, { cwd: root }));
+  const real = realPath || ((rel) => repoRealPath(root, rel));
+  const commit = await headCommit(git);
+  const symbols = [];
+  const started = now();
+  for (const symbol of picked.symbols) {
+    if (now() - started > TOTAL_BUDGET_MS) {
+      symbols.push({ symbol, status: 'not_searched', reason: `the ${TOTAL_BUDGET_MS / 1000}s search budget for this story was spent on earlier symbols` });
+      continue;
+    }
+    symbols.push(await searchSymbol(symbol, { run: git, realPath: real }));
+  }
+  for (const symbol of picked.refused) symbols.push({ symbol, status: 'not_searched', reason: SECRET_REASON });
+  fitFileLists(symbols);
+
+  const callSites = {
+    version: CALL_SITES_VERSION,
+    commit,
+    scope: SCOPE,
+    prose_globs: PROSE_EXTENSIONS.map((e) => `*.${e}`),
+    symbols,
+    omitted: picked.omitted,
+    omitted_total: picked.omittedTotal,
+  };
+  notes.push(...describeCallSites(callSites));
+  return { callSites, notes };
+}
+
+/** The operator's lines for a result: one info line per symbol that is whole, a warning for each that is not. */
+function describeCallSites(callSites) {
+  const notes = [];
+  const where = callSites.commit ? `tracked files at ${callSites.commit.slice(0, 12)}` : 'tracked files (commit unknown)';
+  notes.push(info(`  → call sites: searched ${callSites.symbols.length} symbol(s) the story names, in ${where}`));
+  for (const s of callSites.symbols) {
+    if (s.status === 'not_searched') {
+      notes.push(warn(`  ⚠ call sites for ${s.symbol}: NOT SEARCHED — ${s.reason}; the planner will have no enumeration of it`));
+      continue;
+    }
+    const files = [...new Set(s.hits.map((h) => h.path))];
+    const names = files.slice(0, 4).join(', ') + (s.files > 4 ? `, +${s.files - 4} more` : '');
+    const listable = s.total - s.withheld;
+    const binary = s.binary || 0;
+    const extra = [
+      s.prose ? `${s.prose} more in documentation` : '',
+      s.withheld ? `${s.withheld} in withheld paths` : '',
+      binary ? `${binary} binary file${binary === 1 ? '' : 's'} match and cannot be listed` : '',
+    ].filter(Boolean).join('; ');
+    const fileLevel = s.status === 'incomplete' && binary === 0 && s.file_list_complete === true && Array.isArray(s.file_list);
+    if (s.status === 'incomplete' && fileLevel) {
+      notes.push(info(`     ${s.symbol}: COMPLETE AT FILE LEVEL — ${listable} hits in ${s.files} file${s.files === 1 ? '' : 's'}; the first ${s.hits.length} are listed and every file with a hit is named with its count${s.withheld ? `; EXCEPT ${s.withheld} hit${s.withheld === 1 ? '' : 's'} in withheld paths the planner cannot see` : ''}${s.prose ? `; ${s.prose} more in documentation` : ''}`));
+    } else if (s.status === 'incomplete') {
+      notes.push(warn(`  ⚠ call sites for ${s.symbol}: INCOMPLETE — ${s.hits.length} of ${listable} hits listed (cap ${MAX_HITS_PER_SYMBOL}${s.file_list ? `, ${s.file_list.length} of ${s.files} files named` : ''}); the planner cannot claim an enumeration${extra ? ` (${extra})` : ''}`));
+    } else if (listable === 0 && s.withheld === 0 && s.prose === 0) {
+      notes.push(info(`     ${s.symbol}: 0 hits in any searched file (the symbol may be one this story creates, or spelled differently)`));
+    } else if (listable === 0 && s.withheld === 0) {
+      notes.push(info(`     ${s.symbol}: 0 hits in code files; ${s.prose} in documentation only`));
+    } else if (s.withheld > 0) {
+      notes.push(warn(`  ⚠ call sites for ${s.symbol}: COMPLETE except ${s.withheld} hit${s.withheld === 1 ? '' : 's'} in withheld paths the planner cannot see — ${listable} listed${names ? ` (${names})` : ''}; "the only caller" cannot be claimed${s.prose ? `; ${s.prose} more in documentation` : ''}`));
+    } else {
+      notes.push(info(`     ${s.symbol}: ${listable} hit${listable === 1 ? '' : 's'} in ${s.files} file${s.files === 1 ? '' : 's'}${names ? ` (${names})` : ''}${extra ? `; ${extra}` : ''}`));
+    }
+  }
+  const omittedTotal = callSites.omitted_total || 0;
+  if (omittedTotal > 0) {
+    const shown = callSites.omitted.join(', ') + (omittedTotal > callSites.omitted.length ? ', …' : '');
+    notes.push(warn(`  ⚠ call sites: the story names ${omittedTotal} more compound identifier(s) beyond the ${MAX_SYMBOLS}-symbol cap — NOT SEARCHED: ${shown}`));
+  }
+  return notes;
+}
+
+module.exports = {
+  CALL_SITES_VERSION,
+  SCOPE,
+  MAX_SYMBOLS,
+  MAX_REFUSED,
+  MAX_FILE_LIST_FILES,
+  MAX_FILE_LIST_BYTES,
+  SECRET_NAME,
+  MAX_OMITTED_NAMES,
+  MAX_HITS_PER_SYMBOL,
+  MAX_LINE_CHARS,
+  MAX_PATH_CHARS,
+  MAX_SYMBOL_CHARS,
+  PROSE_EXTENSIONS,
+  SEARCH_TIMEOUT_MS,
+  TOTAL_BUDGET_MS,
+  MAX_OUTPUT_BYTES,
+  isCompoundIdentifier,
+  pickSymbols,
+  fitFileLists,
+  runGit,
+  parseGrepOutput,
+  classifyPath,
+  lineText,
+  searchSymbol,
+  collectCallSites,
+  describeCallSites,
+};