@hone-ai/cli 1.40.0 → 1.42.0

package/lib/block-grammar.js

@@ -167,6 +167,39 @@ const EDIT_SPLIT_RE = /^<{3,}[ \t]*OLD[ \t]*\r?\n([\s\S]*?)\r?\n={3,}[ \t]*\r?\n
 /** A `DELETE: <path>` line. */
 const DELETE_RE = /^[ \t]*DELETE:[ \t]*(\S.*?)[ \t]*$/gim;
 
+/**
+ * HC-GF-404: the [from, to) of every `file:` block FILE_BLOCK_RE matches, rejected or duplicate
+ * paths included, in ascending order. A whole file's content is data: a line-start `edit:` opener
+ * or `DELETE:` line inside one is an example the file holds, never a block of its own.
+ */
+function fileBlockSpans(text) {
+  const spans = [];
+  for (const m of String(text == null ? '' : text).matchAll(FILE_BLOCK_RE)) {
+    spans.push({ from: m.index, to: m.index + m[0].length });
+  }
+  return spans;
+}
+
+/**
+ * HC-GF-404: every match of `re` over `text` that does not start inside one of `spans`
+ * (fileBlockSpans() of the same text). A match that starts inside a span is not dropped after the
+ * fact: the scan resumes at that span's end, because a phantom match can run past the span (a nested
+ * edit with a fence wider than the file's) and swallow a real block after it. `re` is cloned, so the
+ * shared /g regexes above are never advanced.
+ */
+function* matchesOutside(re, text, spans) {
+  const r = new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
+  const s = String(text == null ? '' : text);
+  let i = 0;
+  let m;
+  while ((m = r.exec(s)) !== null) {
+    while (i < spans.length && spans[i].to <= m.index) i++;
+    if (i < spans.length && m.index >= spans[i].from) { r.lastIndex = spans[i].to; continue; }
+    if (m[0].length === 0) r.lastIndex++;
+    yield m;
+  }
+}
+
 module.exports = {
   fenceWidth,
   closesFence,
@@ -178,4 +211,6 @@ module.exports = {
   EDIT_OPEN_RE,
   EDIT_SPLIT_RE,
   DELETE_RE,
+  fileBlockSpans,
+  matchesOutside,
 };

package/lib/bundle-context.js

@@ -35,6 +35,7 @@
  */
 
 const path = require('path');
+const { pathRefusal } = require('./path-refusal');
 
 /**
  * Repo-level files worth bundling regardless of what the story says. Deliberately
@@ -50,18 +51,12 @@ const SIGNAL_FILES = Object.freeze([
 ]);
 
 /**
- * A path that must never reach an agent prompt. Matched on the BASENAME so a nested
- * `config/.env` is caught too. The `.example`/`.sample`/`.template` suffixes are the
- * documented exception and are handled by testing them first.
+ * Is this path a credential file that must never be sent as whole content? `.env.example` is not;
+ * `.env.production` and `keys/deploy.key` are. HC-GF-398: the patterns live in `./path-refusal`
+ * (egress mode); this name stays for the callers that still use it.
  */
-const SECRET_BASENAMES = [/^\.env($|\.)/i, /^secrets?\./i, /\.pem$/i, /\.p12$/i, /(^|[._-])id_(rsa|dsa|ecdsa|ed25519)$/i];
-const SECRET_EXEMPT = /\.(example|sample|template|dist)$/i;
-
-/** Is this path a credential file? `.env.example` is not; `.env.production` is. */
 function isSecretPath(p) {
-  const base = path.posix.basename(String(p || '').replace(/\\/g, '/'));
-  if (SECRET_EXEMPT.test(base)) return false;
-  return SECRET_BASENAMES.some((re) => re.test(base));
+  return pathRefusal(p, { mode: 'egress' }) !== null;
 }
 
 /**
@@ -146,7 +141,7 @@ function nearestPopulatedAncestor(pendingPath, repoFiles) {
 function selectBundle({ named = [], repoFiles = [], exists = () => false, maxSiblings = 6 } = {}) {
   const present = [], pending = [], refused = [];
   for (const p of named) {
-    if (isSecretPath(p)) { refused.push(p); continue; }
+    if (pathRefusal(p, { mode: 'egress' })) { refused.push(p); continue; }
     (exists(p) ? present : pending).push(p);
   }
 
@@ -168,7 +163,7 @@ function selectBundle({ named = [], repoFiles = [], exists = () => false, maxSib
       (path.posix.extname(b) === ext) - (path.posix.extname(a) === ext));
     for (const k of ranked) {
       if (siblings.length >= maxSiblings) break;
-      if (taken.has(k) || isSecretPath(k) || isGeneratedPath(k)) continue;
+      if (taken.has(k) || pathRefusal(k, { mode: 'egress' }) || isGeneratedPath(k)) continue;
       taken.add(k); siblings.push(k);
     }
   }

package/lib/bundle-limits.js

@@ -0,0 +1,10 @@
+'use strict';
+/**
+ * HC-GF-390: the leaf home of the bundle's per-file cap. run-context.js windows a file whose text is
+ * longer than this (bundle-paths.js `planFileExcerpt`: `text.length <= limit` is sent whole), and
+ * review-diff.js diffs exactly the files a reviewer saw only windows of, so both read it from here.
+ * run-context.js re-exports it under the same name for the tests that import it from there.
+ */
+const BUNDLE_MAX_PER_FILE_CHARS = 25_000;
+
+module.exports = { BUNDLE_MAX_PER_FILE_CHARS };

package/lib/call-sites.js

@@ -17,7 +17,7 @@
  *  - 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,
+ *  - A line from a hidden or credential-looking path is never sent (cli/lib/path-refusal.js in content mode,
  *    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
@@ -65,7 +65,8 @@
 const { execFile } = require('node:child_process');
 const path = require('node:path');
 const { gitEnv } = require('./git-env');
-const { contentRefusal, repoRealPath } = require('./context-reserve');
+const { repoRealPath } = require('./context-reserve');
+const { pathRefusal } = require('./path-refusal');
 
 const CALL_SITES_VERSION = 1;
 /** The only scope id today; the server writes its own description of it. */
@@ -73,9 +74,22 @@ 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. */
+// HC-GF-385: 16, up from 6. Six slots spent on string keys (`step_0b`, `config`) left the functions a story changes
+// NOT SEARCHED and hard-stopped step_1 four times on one story. The wire budget is held by MAX_TOTAL_HITS, not by
+// the symbol count: a symbol past it is sent as its per-file list (FILES ONLY), so 16 costs what 6 did.
+const MAX_SYMBOLS = 16;
+/** Secret-looking names are reported, not searched; they take no slot of the 16 but are reported up to this many. */
 const MAX_REFUSED = 2;
+/**
+ * HC-GF-385: the hit lines ALL symbols together may send, spent in rank order: today's 6 x 40, so the 448 KiB
+ * per-story wire budget (server/src/lib/batch-body-limit.js) and its test keep their meaning. A symbol reached after
+ * it is spent sends `hits: []` plus its per-file list.
+ */
+const MAX_TOTAL_HITS = 240;
+/** HC-GF-385: the definition probe ranks at most this many candidates, best-ranked first. */
+const MAX_PROBE_CANDIDATES = 32;
+/** HC-GF-385: the probe's own share of TOTAL_BUDGET_MS; past it the story's own order is kept, and said. */
+const PROBE_TIMEOUT_MS = 8_000;
 /** 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). */
@@ -97,7 +111,38 @@ const PROSE_EXTENSIONS = Object.freeze(['md', 'mdx', 'markdown', 'rst', 'adoc',
 
 // ── Choosing the symbols ────────────────────────────────────────────────────────────────────────
 
-const BACKTICKED = /`([^`\n]{2,200})`/g;
+// Backticked spans are PAIRED first, by the CommonMark rule, and the 2-to-200 rule is applied to each paired span afterwards.
+// A bound INSIDE a regex decides which backticks pair: at `x`, and `foo` the opening backtick of `x` cannot start a 2-character
+// match, so its closing one does, the "span" is `, and`, and `foo` is lost (measured 2026-10-10 over the roadmap rows: 68 of 939
+// extracted a wrong span set). A plain /`([^`\n]*)`/ fixed that and made the next one: after a run of TWO OR MORE backticks
+// (a ``double`` span, an inline ```fence) the pairing never recovered for the rest of the line, and 7 rows lost symbols the old
+// pattern found. The rule that has no such failure is the one Markdown itself uses: a run of N backticks opens a span that the
+// next run of EXACTLY N backticks closes, and a run with no such closer is literal text. Per line (a span does not cross a
+// newline here, as before). Linear: the next run of the same length is computed once per run, not searched for.
+// The same defect as BACKTICKED_RE in bundle-paths.js (HC-GF-188-followup-2), which has the first fix only.
+function backtickedSpans(text) {
+  const spans = [];
+  for (const line of String(text || '').split('\n')) {
+    if (!line.includes('`')) continue;
+    const runs = [];
+    for (const m of line.matchAll(/`+/g)) runs.push({ at: m.index, len: m[0].length });
+    const nextSame = new Array(runs.length).fill(-1);
+    const lastOfLen = new Map();
+    for (let i = runs.length - 1; i >= 0; i--) {
+      nextSame[i] = lastOfLen.has(runs[i].len) ? lastOfLen.get(runs[i].len) : -1;
+      lastOfLen.set(runs[i].len, i);
+    }
+    for (let i = 0; i < runs.length; i++) {
+      const j = nextSame[i];
+      if (j < 0) continue; // no closer of this length: the run is literal text
+      let span = line.slice(runs[i].at + runs[i].len, runs[j].at);
+      if (span.length > 2 && span.startsWith(' ') && span.endsWith(' ') && /[^ ]/.test(span)) span = span.slice(1, -1); // CommonMark: one space each side
+      spans.push(span);
+      i = j; // resume after the closer; the runs between are inside the span
+    }
+  }
+  return spans;
+}
 // 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).
@@ -158,25 +203,129 @@ function symbolOfSpan(span) {
  * @returns {{symbols: string[], omitted: string[], omittedTotal: number, refused: string[]}}
  */
 function pickSymbols(storyText, { max = MAX_SYMBOLS } = {}) {
+  const { ranked, refusedAll } = rankCandidates(storyText);
+  return sliceRanked(ranked.map((c) => c.name), refusedAll, max);
+}
+
+/**
+ * Every candidate the story names, in the story's order (explicitly written first, then by how often it is named,
+ * ties in the order first named), with the facts that order was made from. Secret-looking names are split off.
+ * Synchronous and text-only: `pickSymbols` keeps that contract for callers this file cannot see (HC-GF-385).
+ * @returns {{ranked: Array<{name: string, explicit: boolean, count: number}>, refusedAll: string[]}}
+ */
+function rankCandidates(storyText) {
   const counts = new Map();
   const explicitNames = new Set();
-  for (const m of String(storyText || '').matchAll(BACKTICKED)) {
-    const sym = symbolOfSpan(m[1]);
+  for (const span of backtickedSpans(storyText)) {
+    if (span.length < 2 || span.length > 200) continue; // the length rule, after pairing
+    const sym = symbolOfSpan(span);
     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),
+    ranked: all.filter((n) => !SECRET_NAME.test(n)).map((name) => ({ name, explicit: explicitNames.has(name), count: counts.get(name) })),
+    refusedAll: all.filter((n) => SECRET_NAME.test(n)),
+  };
+}
+
+/** The first `max` names are searched; the rest, and the refused names past MAX_REFUSED, are reported as omitted. */
+function sliceRanked(names, refusedAll, max) {
+  const beyond = [...names.slice(max), ...refusedAll.slice(MAX_REFUSED)];
+  return {
+    symbols: names.slice(0, max),
     omitted: beyond.slice(0, MAX_OMITTED_NAMES),
     omittedTotal: beyond.length,
-    refused,
+    refused: refusedAll.slice(0, MAX_REFUSED),
+  };
+}
+
+// ── Ranking by definition (HC-GF-385) ───────────────────────────────────────────────────────────
+
+/** Files whose matches never define code: documentation, and data formats (an object or YAML key is not a symbol). */
+const DATA_EXTENSIONS = Object.freeze(['json', 'jsonc', 'json5', 'yaml', 'yml', 'toml', 'lock', 'csv', 'tsv', 'xml', 'ini', 'env', 'properties']);
+/** A word before `name(` that makes it a call or an expression, never a C-family definition. */
+const NOT_A_RETURN_TYPE = new Set(['return', 'await', 'new', 'throw', 'yield', 'else', 'case', 'typeof', 'delete', 'void', 'in', 'of', 'do',
+  'if', 'while', 'for', 'switch', 'catch', 'and', 'or', 'not', 'is', 'as', 'echo', 'print', 'puts', 'go', 'defer', 'export', 'default']);
+
+/**
+ * How strongly one line defines `name`: 2 for a function, method, class or type; 1 for a top-level or exported
+ * constant or variable; 0 for anything else (a call, a key, a mention). Language-neutral patterns, covering
+ * JavaScript and TypeScript, Python, Go, Ruby, Java and the C family, and `fn`/`fun`/`func` (Rust, Kotlin, Swift).
+ * `name` is an identifier ([A-Za-z0-9_]), so it is safe inside a RegExp.
+ * @param {string} line
+ * @param {string} name
+ * @returns {0|1|2}
+ */
+function definitionTier(line, name) {
+  const n = `${name}(?![A-Za-z0-9_$])`;
+  const t = String(line);
+  // A keyword that introduces a definition: `function f`, `class C`, `def f`, `def self.f`, `func (r *T) f`, `fn f`, `fun f`.
+  if (new RegExp(`(?:^|[^A-Za-z0-9_$.])(?:function\\*?|class|def|func|fn|fun|interface|enum|struct|trait|type|module|record|protocol)\\s+(?:self\\.)?(?:\\([^)]*\\)\\s*)?${n}`).test(t)) return 2;
+  // A function value bound at top level or exported: `export const f = async (a) =>`, `const f = function`.
+  if (new RegExp(`^(?:export\\s+)?(?:const|let|var)\\s+${n}\\s*=\\s*(?:async\\b\\s*)?(?:function\\b|\\([^)]*\\)\\s*=>|[A-Za-z_$][A-Za-z0-9_$]*\\s*=>)`).test(t)) return 2;
+  // A method, in a class body or an object literal: `  async f(a, b) {`, `  static get f() {`.
+  if (new RegExp(`^\\s*(?:(?:static|async|get|set|public|private|protected|readonly|override|abstract|final)\\s+)*${n}\\s*\\([^)]*\\)\\s*(?::\\s*[^={;]+)?\\{`).test(t)) return 2;
+  // A C-family signature: one or more type words, then `name(`, and no `;` (a prototype or a call statement).
+  const sig = new RegExp(`^\\s*((?:[A-Za-z_][A-Za-z0-9_<>\\[\\],:*&?]*\\s+)+)\\*?${n}\\s*\\([^;]*$`).exec(t);
+  if (sig) {
+    const words = sig[1].trim().split(/\s+/);
+    if (!NOT_A_RETURN_TYPE.has(words[words.length - 1])) return 2;
+  }
+  // A top-level or exported binding of anything else: `const f =`, `export let f`, `module.exports.f =`, Go `var f`.
+  if (new RegExp(`^(?:export\\s+)?(?:const|let|var|val)\\s+${n}`).test(t)) return 1;
+  if (new RegExp(`^(?:module\\.)?exports\\.${n}\\s*=`).test(t)) return 1;
+  // Python and Ruby top-level assignment: `f = ...` at column 0, not `f == x`.
+  if (new RegExp(`^${n}\\s*=(?!=)`).test(t)) return 1;
+  return 0;
+}
+
+/**
+ * Rank candidates by whether the repository defines them, with ONE batched `git grep -F -w` over all of them.
+ * Functions, methods, classes and types come first, then top-level or exported constants, then names with no
+ * definition (string keys, config fields, words). Within a tier the story's own order holds. Any failure, timeout
+ * or output this cannot read keeps the story's order, and the note says so: a probe never empties the search.
+ * @param {Array<{name: string}>} ranked  the story's order
+ * @returns {Promise<{ranked: Array<{name: string}>, fallback: string|null, undefinedNames: string[]}>}
+ */
+async function rankByDefinition(ranked, { run, realPath }) {
+  if (ranked.length === 0) return { ranked, fallback: null, undefinedNames: [] };
+  const probed = ranked.slice(0, MAX_PROBE_CANDIDATES);
+  const argv = ['grep', '-n', '-z', '-w', '-F', '-I', '--no-color', '--no-recurse-submodules'];
+  for (const c of probed) argv.push('-e', c.name);
+  let r;
+  try { r = await run(argv, { timeoutMs: PROBE_TIMEOUT_MS }); } catch { r = { failure: 'the probe could not be run' }; }
+  const problem = grepProblem(r || {});
+  if (problem) return { ranked, fallback: `the definition probe gave no answer (${problem}), so the story's own order was used`, undefinedNames: [] };
+  const lines = r.status === 1 ? [] : parseGrepOutput(r.stdout);
+  if (lines === null) return { ranked, fallback: 'the definition probe printed output that could not be read, so the story\'s own order was used', undefinedNames: [] };
+
+  const tier = new Map(probed.map((c) => [c.name, 0]));
+  const kinds = new Map();
+  const wordRe = /[A-Za-z_$][A-Za-z0-9_$]*/g;
+  for (const hit of lines) {
+    let kind = kinds.get(hit.path);
+    if (kind === undefined) {
+      const ext = path.posix.extname(hit.path).slice(1).toLowerCase();
+      kind = DATA_EXTENSIONS.includes(ext) ? 'data' : classifyPath(hit.path, realPath);
+      kinds.set(hit.path, kind);
+    }
+    if (kind !== 'ok') continue; // documentation, data and withheld paths define nothing here
+    for (const w of new Set(String(hit.text).match(wordRe) || [])) {
+      if (!tier.has(w) || tier.get(w) === 2) continue;
+      const d = definitionTier(hit.text, w);
+      if (d > tier.get(w)) tier.set(w, d);
+    }
+  }
+  // Stable: within a tier the story's order is kept. Candidates past the probe cap keep their place after the probed.
+  const order = probed.map((c, i) => ({ c, i, t: tier.get(c.name) }))
+    .sort((a, b) => (b.t - a.t) || (a.i - b.i)).map((x) => x.c);
+  return {
+    ranked: [...order, ...ranked.slice(MAX_PROBE_CANDIDATES)],
+    fallback: null,
+    undefinedNames: probed.filter((c) => tier.get(c.name) === 0).map((c) => c.name),
   };
 }
 
@@ -239,7 +388,7 @@ 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';
+  if (pathRefusal(rel, { mode: 'content' })) 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; }
@@ -288,7 +437,7 @@ function parseFileList(out) {
  *  - '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 }) {
+async function searchSymbol(symbol, { run, realPath, maxHits = MAX_HITS_PER_SYMBOL }) {
   // 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' };
@@ -323,7 +472,9 @@ async function searchSymbol(symbol, { run, realPath }) {
     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) }));
+  // HC-GF-385: `maxHits` is what is left of the story's MAX_TOTAL_HITS (0 once it is spent), never more than the per-symbol cap.
+  const cap = Math.max(0, Math.min(MAX_HITS_PER_SYMBOL, Number.isSafeInteger(maxHits) ? maxHits : MAX_HITS_PER_SYMBOL));
+  const hits = sendable.slice(0, cap).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 = {
@@ -336,7 +487,10 @@ async function searchSymbol(symbol, { run, realPath }) {
     binary,
     hits,
   };
-  if (sendable.length > MAX_HITS_PER_SYMBOL) {
+  // HC-GF-385: every searched symbol with a sendable hit carries its per-file list, not only one past the hit cap.
+  // A symbol cut by the total-hit budget needs it to be FILES ONLY, and a whole symbol whose hit lines the server's
+  // render budget drops needs it to stay an enumeration at file level.
+  if (sendable.length > 0) {
     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;
@@ -344,11 +498,17 @@ async function searchSymbol(symbol, { run, realPath }) {
   return entry;
 }
 
-/** Keep the symbols' file lists inside MAX_FILE_LIST_BYTES together; a list that is cut says so. */
+/**
+ * Keep the symbols' file lists inside MAX_FILE_LIST_BYTES together; a list that is cut says so.
+ * HC-GF-385: the bytes go first to the symbols whose hit lines were cut (by the per-symbol cap or the total-hit
+ * budget), in rank order, because for them the list IS the enumeration; then to the rest, in rank order. Spent
+ * in plain rank order, whole symbols at the top starved the FILES ONLY ones below them into INCOMPLETE.
+ */
 function fitFileLists(symbols) {
   let room = MAX_FILE_LIST_BYTES;
-  for (const s of symbols) {
-    if (!s.file_list) continue;
+  const cut = (s) => Array.isArray(s.hits) && Number.isSafeInteger(s.total) && s.hits.length < s.total - (s.withheld || 0);
+  const ordered = [...symbols.filter((s) => s.file_list && cut(s)), ...symbols.filter((s) => s.file_list && !cut(s))];
+  for (const s of ordered) {
     const kept = [];
     for (const f of s.file_list) {
       const size = Buffer.byteLength(JSON.stringify(f), 'utf8') + 1;
@@ -379,8 +539,9 @@ const warn = (text) => ({ level: 'warn', text });
  */
 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 };
+  const { ranked: storyOrder, refusedAll } = rankCandidates(storyText);
+  // The early return comes BEFORE the probe: a story that names nothing searchable runs no git at all.
+  if (storyOrder.length === 0 && refusedAll.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;
@@ -389,17 +550,24 @@ async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now,
     const dir = top.failure || top.status !== 0 ? '' : top.stdout.trim();
     if (dir) root = dir;
   }
-  const git = run || ((argv) => runGit(argv, { cwd: root }));
+  const git = run || ((argv, opts = {}) => runGit(argv, { cwd: root, ...opts }));
   const real = realPath || ((rel) => repoRealPath(root, rel));
   const commit = await headCommit(git);
-  const symbols = [];
+  // HC-GF-385: the clock starts before the probe, so the probe's time comes out of the same TOTAL_BUDGET_MS.
   const started = now();
+  // Rank BEFORE the slice and compute what was omitted AFTER it, or the functions never reach the slice.
+  const probe = await rankByDefinition(storyOrder, { run: git, realPath: real });
+  const picked = sliceRanked(probe.ranked.map((c) => c.name), refusedAll, maxSymbols);
+  const symbols = [];
+  let hitsLeft = MAX_TOTAL_HITS;
   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 }));
+    const entry = await searchSymbol(symbol, { run: git, realPath: real, maxHits: hitsLeft });
+    if (Array.isArray(entry.hits)) hitsLeft = Math.max(0, hitsLeft - entry.hits.length);
+    symbols.push(entry);
   }
   for (const symbol of picked.refused) symbols.push({ symbol, status: 'not_searched', reason: SECRET_REASON });
   fitFileLists(symbols);
@@ -413,12 +581,17 @@ async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now,
     omitted: picked.omitted,
     omitted_total: picked.omittedTotal,
   };
-  notes.push(...describeCallSites(callSites));
+  if (probe.fallback) notes.push(warn(`  ⚠ call sites: ${probe.fallback}`));
+  const searchedUndefined = probe.undefinedNames.filter((n) => picked.symbols.includes(n));
+  if (!probe.fallback && searchedUndefined.length > 0) {
+    notes.push(info(`     no definition found for ${searchedUndefined.join(', ')} (ranked after defined code; it may be a key, a field, or one this story creates)`));
+  }
+  notes.push(...describeCallSites(callSites, { maxSymbols }));
   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) {
+function describeCallSites(callSites, { maxSymbols = MAX_SYMBOLS } = {}) {
   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}`));
@@ -437,7 +610,10 @@ function describeCallSites(callSites) {
       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) {
+    if (s.status === 'incomplete' && fileLevel && s.hits.length === 0) {
+      // HC-GF-385: reached after the total-hit budget was spent. The server renders it FILES ONLY.
+      notes.push(info(`     ${s.symbol}: FILES ONLY — ${listable} hits in ${s.files} file${s.files === 1 ? '' : 's'}; every file with a hit is named with its count, individual lines not sent (the ${MAX_TOTAL_HITS}-hit budget was spent on higher-ranked symbols)${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' && 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})` : ''}`));
@@ -454,16 +630,21 @@ function describeCallSites(callSites) {
   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}`));
+    notes.push(warn(`  ⚠ call sites: the story names ${omittedTotal} more compound identifier(s) beyond the ${maxSymbols}-symbol cap — NOT SEARCHED: ${shown}`));
   }
   return notes;
 }
 
 module.exports = {
+  backtickedSpans,
   CALL_SITES_VERSION,
   SCOPE,
   MAX_SYMBOLS,
   MAX_REFUSED,
+  MAX_TOTAL_HITS,
+  MAX_PROBE_CANDIDATES,
+  PROBE_TIMEOUT_MS,
+  DATA_EXTENSIONS,
   MAX_FILE_LIST_FILES,
   MAX_FILE_LIST_BYTES,
   SECRET_NAME,
@@ -478,6 +659,9 @@ module.exports = {
   MAX_OUTPUT_BYTES,
   isCompoundIdentifier,
   pickSymbols,
+  rankCandidates,
+  definitionTier,
+  rankByDefinition,
   fitFileLists,
   runGit,
   parseGrepOutput,

package/lib/context-reserve.js

@@ -31,7 +31,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { remedyFor, partitionSafePaths, tokenOf, isSafeToken } = require('./hard-pause-remedy');
 const { parseIncludeTarget } = require('./include-paths');
-const { isSecretPath } = require('./bundle-context');
+const { pathRefusal, structuralRefusal } = require('./path-refusal');
 const { isBatchId } = require('./run-target');
 
 /** The start of the reason a re-served run is killed with. The loop reads it back to find the new batch. */
@@ -67,18 +67,6 @@ function hardPauseRequest(run) {
   return remedy && remedy.stepKey === at[1] ? remedy : null;
 }
 
-// Credential-looking names the bundler's own refusal (isSecretPath) does not cover: a public half of a key pair,
-// key containers, anything the author named a secret or a credential.
-const SECRET_LOOKING = [/(^|[._-])id_(rsa|dsa|ecdsa|ed25519)/i, /\.(key|pfx|jks|keystore|p8)$/i, /(secret|credential)/i];
-
-/** Why a path is not a plain relative path, or null. `file` has no `:line` or `:symbol` suffix. */
-function structuralRefusal(file) {
-  if (typeof file !== 'string' || file === '') return 'empty';
-  if (/^[-/~]/.test(file)) return 'absolute, home-relative or option-like';
-  if (/[\\\0]/.test(file)) return 'not a plain relative path';
-  if (file.split('/').some((s) => s === '' || s === '.' || s === '..')) return 'not a plain relative path';
-  return null;
-}
 
 /**
  * Why the CONTENT of a path (a plain file path, no `:line`) must not be sent to a model, or null: the three
@@ -87,11 +75,7 @@ function structuralRefusal(file) {
  * @param {string} file
  */
 function contentRefusal(file) {
-  const plain = structuralRefusal(file);
-  if (plain) return plain;
-  if (isSecretPath(file) || SECRET_LOOKING.some((re) => re.test(path.posix.basename(file)))) return 'looks like a credential file';
-  if (file.split('/').some((s) => s.startsWith('.'))) return 'a hidden file or directory';
-  return null;
+  return pathRefusal(file, { mode: 'content' });
 }
 
 /**
@@ -208,21 +192,24 @@ function batchIdFromQueueOutput(stdout) {
  * status, created_at, error_message), newest first.
  *  - `later`: a run of the story in this repository, created AFTER the paused one and not killed. A re-serve that
  *    queued but whose kill failed, or that died between the two, leaves exactly this and no marker.
- *  - `earlier`: a run of the story killed with `re-served as batch <id>` BEFORE this one, so this run is that
- *    re-serve (the loop was started on the new batch alone) and a second pause here is the second.
- *  - `unknown`: the paused run's creation time is not a date, so neither can be told.
- * @returns {{kind: 'later'|'earlier'|'unknown', runId?: string, batchId?: string}|null}
+ *  - `earlier`: a run of the story, older than this one, killed with `re-served as batch <id>` where <id> is the batch
+ *    THIS run is in (`batchId`): this run is that re-serve (the loop was started on the new batch alone), and a second
+ *    pause here is the second. A story re-served into some OTHER batch, however long ago, is history and not this
+ *    run's lineage: it neither blocks nor justifies anything (HC-GF-351-followup-1).
+ *  - `unknown`: the paused run's creation time is not a date or its batch id is not one, so neither can be told.
+ * @returns {{kind: 'later'|'earlier'|'unknown', runId?: string, batchId?: string, why?: string}|null}
  */
-function serveHistory(rows, { runId, storyId, repoName, since }) {
+function serveHistory(rows, { runId, storyId, repoName, since, batchId: ownBatch }) {
   const t0 = Date.parse(since);
-  if (!Number.isFinite(t0)) return { kind: 'unknown' };
+  if (!Number.isFinite(t0)) return { kind: 'unknown', why: 'its creation time is not known' };
+  if (!isBatchId(ownBatch)) return { kind: 'unknown', why: 'the batch it is in is not known' };
   for (const row of Array.isArray(rows) ? rows : []) {
     if (!row || row.id === runId || row.story_id !== storyId || row.repo_name !== repoName) continue;
     const t = Date.parse(row.created_at);
     if (!Number.isFinite(t)) continue;
     if (t > t0 && row.status !== 'killed') return { kind: 'later', runId: row.id };
-    const batchId = t < t0 ? reservedBatchOf({ status: row.status, errorMessage: row.error_message }) : null;
-    if (batchId) return { kind: 'earlier', runId: row.id, batchId };
+    const reserved = t < t0 ? reservedBatchOf({ status: row.status, errorMessage: row.error_message }) : null;
+    if (reserved && reserved === ownBatch) return { kind: 'earlier', runId: row.id, batchId: reserved };
   }
   return null;
 }